mustflow 2.107.1 → 2.107.9

package/README.md

@@ -269,6 +269,7 @@ mf run mustflow_update_apply
 | `mf onboard commands` | Suggest review-only command-intent snippets from package.json, Makefile, or justfile without writing files or granting command authority. |
 | `mf next` | Inspect install state, changed files, verification coverage, and command-contract gaps, then print the next safe mustflow action without running commands. |
 | `mf evidence` | Summarize changed-file verification requirements, risk-priced evidence assessment, latest failure replay capsule, conflict ledger, receipts, remaining risks, and gaps without running commands. |
+| `mf workspace scan` | Scan a `projects/` directory for nested repositories without requiring workspace configuration or granting command authority. |
 | `mf workspace status` | Inspect configured workspace roots and nested repository contract readiness without granting parent-to-child command authority. |
 | `mf workspace command-catalog` | Aggregate per-repository command intent availability with safe `mf run` entrypoints and no raw command strings. |
 | `mf workspace verify --changed --plan-only` | Aggregate per-repository changed-file verification plans without running commands or granting parent-to-child command authority. |
@@ -369,6 +370,9 @@ commands when a repository uses another runner or has a faster related-test entr
 - `lifecycle = "oneshot"`
 - `run_policy = "agent_allowed"`
 - `stdin = "closed"`
+- `timeout_seconds` is a positive integer
+- a command is declared with `argv`, or with `mode = "shell"` plus `cmd` and `allow_shell = true`
+- `cwd` resolves inside the current mustflow root
 
 Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly. `mf run` also rejects obvious long-running `argv` shapes, such as shell-wrapper background payloads, interpreter loops, package-manager development scripts, watchers, and development servers declared as one-shot commands. If a bounded one-shot command has a name that matches a common long-running pattern, the intent can explicitly acknowledge that with `allow_long_running_command_patterns = true`; background shell patterns remain blocked.
 
@@ -468,6 +472,7 @@ mf run docs_validate_fast
 mf run docs_validate
 mf run mustflow_check
 mf run release_npm_version_available
+mf run release_npm_publish
 mf run release_npm_published_verify
 ```
 
@@ -481,7 +486,7 @@ Run the full release check before publishing:
 bun run release:check
 ```
 
-`release:check` validates the CLI, builds the documentation site, packs the npm tarball, installs it into a temporary project, and runs the public `mf` workflow. Maintainer npm publishing uses the `Publish npm package` GitHub Actions workflow from a published GitHub Release. The release tag must match the `package.json` version, with an optional leading `v`. Run `mf run release_npm_version_available` before creating the tag and `mf run release_npm_published_verify` after the publish workflow completes. npm Trusted Publishing must be configured for the workflow before maintainers publish through it.
+`release:check` validates the CLI, builds the documentation site, packs the npm tarball, installs it into a temporary project, and runs the public `mf` workflow. Maintainer npm publishing uses the `Publish npm package` GitHub Actions workflow from a release tag. The release tag must match the `package.json` version, with an optional leading `v`. Run `mf run release_npm_version_available` before creating the tag, `mf run release_npm_publish` to push the release tag that triggers trusted publishing and GitHub Release creation, and `mf run release_npm_published_verify` after the publish workflow completes. npm Trusted Publishing must be configured for the workflow before maintainers publish through it.
 
 ## Documentation site
 

package/dist/cli/commands/init.js

@@ -1,4 +1,4 @@
-import { existsSync, readSync } from 'node:fs';
+import { existsSync, lstatSync, readSync } from 'node:fs';
 import path from 'node:path';
 import { stdin as processStdin, stdout as processStdout } from 'node:process';
 import { createInterface } from 'node:readline/promises';
@@ -9,6 +9,7 @@ import { isLocaleTag } from '../lib/locale-tags.js';
 import { MANIFEST_LOCK_RELATIVE_PATH, sha256File } from '../lib/manifest-lock.js';
 import { formatCliOptionParseError, hasCliOptionToken, parseCliOptions } from '../lib/option-parser.js';
 import { isCommitMessageStyle, isTestAuthoringPolicy } from '../lib/preferences-options.js';
+import { discoverNestedRepositories, getRepoMapConfig } from '../lib/repo-map.js';
 import { getDefaultTemplate, getTemplateFiles } from '../lib/templates.js';
 const MUSTFLOW_BLOCK_START = '<!-- mustflow:start schema=1 -->';
 const MUSTFLOW_BLOCK_END = '<!-- mustflow:end -->';
@@ -17,6 +18,8 @@ const GITIGNORE_FRAGMENT_RELATIVE_PATH = 'gitignore.mustflow';
 const NON_INTERACTIVE_PROMPT_MAX_BYTES = 16 * 1024;
 const NON_INTERACTIVE_PROMPT_MAX_RESPONSES = 64;
 const NON_INTERACTIVE_PROMPT_READ_CHUNK_BYTES = 4096;
+const WORKSPACE_INIT_REPOSITORY_THRESHOLD = 2;
+const DEFAULT_WORKSPACE_SCAN_ROOT = 'projects';
 const LOCALE_LABELS = {
     en: 'English',
     ko: 'Korean',
@@ -540,6 +543,47 @@ function shouldPromptForInit(args, options) {
     }
     return Boolean(processStdin.isTTY && processStdout.isTTY);
 }
+function hasGitMarker(directoryPath) {
+    try {
+        const marker = lstatSync(path.join(directoryPath, '.git'));
+        return marker.isDirectory() || marker.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function hasInstalledMustflowMarker(directoryPath) {
+    return existsSync(path.join(directoryPath, 'AGENTS.md')) || existsSync(path.join(directoryPath, '.mustflow'));
+}
+function countDefaultWorkspaceRepositories(targetRoot) {
+    const config = getRepoMapConfig(targetRoot);
+    const repositories = discoverNestedRepositories(targetRoot, { ...config.map, includeNested: true }, {
+        ...config.workspace,
+        enabled: true,
+        roots: [DEFAULT_WORKSPACE_SCAN_ROOT],
+    });
+    return repositories.length;
+}
+/**
+ * mf:anchor cli.init.workspace-root-guard
+ * purpose: Detect multi-repository workspace roots before installing repository-scoped mustflow files.
+ * search: mf init, workspace root, projects directory, nested repositories, install guard
+ * invariant: Non-git workspace folders with multiple nested repositories should not receive repo-scoped AGENTS.md by default.
+ * risk: config, state
+ */
+function shouldRefuseWorkspaceRootInit(targetRoot) {
+    if (hasGitMarker(targetRoot) || hasInstalledMustflowMarker(targetRoot)) {
+        return false;
+    }
+    return countDefaultWorkspaceRepositories(targetRoot) >= WORKSPACE_INIT_REPOSITORY_THRESHOLD;
+}
+function printWorkspaceRootInitRefusal(targetRoot, reporter, lang) {
+    reporter.stderr(t(lang, 'init.error.workspaceRootDetected', {
+        count: countDefaultWorkspaceRepositories(targetRoot),
+        projectsDir: DEFAULT_WORKSPACE_SCAN_ROOT,
+    }));
+    reporter.stderr(t(lang, 'init.error.workspaceRootGuidance'));
+}
 async function promptChoice(reader, reporter, lang, question, choices, defaultValue) {
     const defaultIndex = Math.max(0, choices.findIndex((choice) => choice.value === defaultValue));
     reporter.stdout('');
@@ -944,6 +988,10 @@ export async function runInit(args, reporter, lang = 'en') {
     }
     const targetRoot = process.cwd();
     let template;
+    if (shouldRefuseWorkspaceRootInit(targetRoot)) {
+        printWorkspaceRootInitRefusal(targetRoot, reporter, lang);
+        return 1;
+    }
     try {
         template = getDefaultTemplate();
     }

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

@@ -174,6 +174,13 @@ function createRunProgressReporter(input) {
         }
     };
 }
+/**
+ * mf:anchor cli.run.execute
+ * purpose: Coordinate approved run-plan execution with active locks, environment policy, output limits, and write drift.
+ * search: run plan execution, active lock, environment policy, write drift, receipt
+ * invariant: Trusted root, runnable plan, active lock, and receipt tracking remain one preflight chain.
+ * risk: config, security, state
+ */
 export async function executeRunCommand(request, reporter, lang = 'en', options = {}) {
     const executorStartedAtMs = performance.now();
     const profiler = new RunProfiler();

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

@@ -27,6 +27,13 @@ function normalizeSpawnedCommandInput(command) {
         windowsVerbatimArguments: false,
     };
 }
+/**
+ * mf:anchor cli.run.process-lifecycle
+ * purpose: Spawn configured commands with bounded output and deterministic timeout termination.
+ * search: child process, timeout, process tree, output limit, kill after
+ * invariant: Timed-out or output-limited commands must stop the process tree and return bounded stdout and stderr snapshots.
+ * risk: state, security
+ */
 function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
     if (command.executable.trim().length === 0) {
         return Promise.resolve({

package/dist/cli/commands/verify.js

@@ -600,6 +600,13 @@ function toParallelismReport(settings) {
         note: settings.note,
     };
 }
+/**
+ * mf:anchor cli.verify.receipt-manifest
+ * purpose: Persist verify receipts, latest summary, failure evidence, and completion verdict in one state update boundary.
+ * search: mf verify, receipt manifest, latest run, completion verdict, failure fingerprint
+ * invariant: Receipt paths and verdict evidence must share the same verification_plan_id.
+ * risk: state, data_consistency
+ */
 function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks, scopeDiffRisks, validationRatchetRisks, reproEvidence, externalChecks) {
     const statePaths = createVerifyRunStatePaths(projectRoot);
     const receipts = [];
@@ -770,6 +777,13 @@ function writeVerifyRunReceipts(projectRoot, output, report, sourceAnchorRisks,
     updateRunReceiptState(projectRoot, resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
     return outputWithReceiptPaths;
 }
+/**
+ * mf:anchor cli.verify.output-model
+ * purpose: Create the verification output from classification, command contract, selected intents, and evidence risk models.
+ * search: verification output, risk assessment, source anchors, validation ratchet, external evidence
+ * invariant: Completion verdict risk counts must be derived from the same report and results that produce receipts.
+ * risk: state, data_consistency
+ */
 async function createVerifyOutput(input, planSource, projectRoot, lang, reproEvidence = null, externalChecks = [], parallelism = DEFAULT_VERIFY_PARALLELISM, parallelismReport = null) {
     const contract = readCommandContract(projectRoot);
     const report = createChangeVerificationReport(input.classificationReport, contract, projectRoot);

package/dist/cli/commands/workspace.js

@@ -9,9 +9,15 @@ import { resolveMustflowRoot } from '../lib/project-root.js';
 import { getRepoMapConfig, discoverNestedRepositories } from '../lib/repo-map.js';
 import { createRunPlan } from '../lib/run-plan.js';
 import { readCommandContract, readString, readStringArray } from '../../core/config-loading.js';
+const DEFAULT_WORKSPACE_SCAN_ROOT = 'projects';
+const WORKSPACE_SCAN_SCHEMA_VERSION = '1';
 const WORKSPACE_STATUS_SCHEMA_VERSION = '1';
 const WORKSPACE_COMMAND_CATALOG_SCHEMA_VERSION = '1';
 const WORKSPACE_VERIFICATION_PLAN_SCHEMA_VERSION = '1';
+const WORKSPACE_SCAN_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--projects-dir', kind: 'string' },
+];
 const WORKSPACE_STATUS_OPTIONS = [{ name: '--json', kind: 'boolean' }];
 const WORKSPACE_COMMAND_CATALOG_OPTIONS = [{ name: '--json', kind: 'boolean' }];
 const WORKSPACE_VERIFY_OPTIONS = [
@@ -24,6 +30,7 @@ function getWorkspaceHelp(lang = 'en') {
         usage: 'mf workspace <action> [options]',
         summary: t(lang, 'workspace.help.summary'),
         commands: [
+            { label: 'scan', description: t(lang, 'workspace.help.action.scan') },
             { label: 'status', description: t(lang, 'workspace.help.action.status') },
             { label: 'command-catalog', description: t(lang, 'workspace.help.action.commandCatalog') },
             { label: 'verify', description: t(lang, 'workspace.help.action.verify') },
@@ -31,10 +38,13 @@ function getWorkspaceHelp(lang = 'en') {
         options: [
             { label: '--changed', description: t(lang, 'classify.help.option.changed') },
             { label: '--plan-only', description: t(lang, 'verify.help.option.planOnly') },
+            { label: '--projects-dir <path>', description: t(lang, 'workspace.help.option.projectsDir') },
             { label: '--json', description: t(lang, 'cli.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
         examples: [
+            'mf workspace scan --json',
+            'mf workspace scan --projects-dir projects --json',
             'mf workspace status --json',
             'mf workspace command-catalog --json',
             'mf workspace verify --changed --plan-only --json',
@@ -63,6 +73,13 @@ function createWorkspaceVerificationPlanPolicy() {
         selected_intents_run_via: 'mf run <intent>',
     };
 }
+function createAdHocWorkspaceConfig(base, projectsDir) {
+    return {
+        ...base,
+        enabled: true,
+        roots: [projectsDir],
+    };
+}
 function getIntentNames(intents) {
     return Object.keys(intents).sort((left, right) => left.localeCompare(right));
 }
@@ -136,6 +153,13 @@ function summarizeRepository(projectRoot, repository) {
         issues,
     };
 }
+/**
+ * mf:anchor cli.workspace.status-read-model
+ * purpose: Summarize nested repositories and command contracts without granting parent-root command authority.
+ * search: workspace status, nested repositories, command contract, read only, runnable intents
+ * invariant: Workspace status reports observable repo facts and never executes or authorizes child-repository commands.
+ * risk: config, state
+ */
 function createWorkspaceStatusOutput() {
     const projectRoot = resolveMustflowRoot();
     const config = getRepoMapConfig(projectRoot);
@@ -148,18 +172,35 @@ function createWorkspaceStatusOutput() {
         schema_version: WORKSPACE_STATUS_SCHEMA_VERSION,
         command: 'workspace status',
         mustflow_root: projectRoot,
-        workspace: {
-            enabled: config.workspace.enabled,
-            roots: config.workspace.roots,
-            max_depth: config.workspace.maxDepth,
-            max_repositories: config.workspace.maxRepositories,
-            follow_symlinks: config.workspace.followSymlinks,
-            stop_at_repository_root: config.workspace.stopAtRepositoryRoot,
-        },
+        workspace: workspaceConfigOutput(config.workspace),
+        policy: createWorkspaceStatusPolicy(),
+        repository_count: repositories.length,
+        repositories,
+        issues,
+    };
+}
+function createWorkspaceScanOutput(projectsDir) {
+    const projectRoot = resolveMustflowRoot();
+    const config = getRepoMapConfig(projectRoot);
+    const workspace = createAdHocWorkspaceConfig(config.workspace, projectsDir);
+    const repositories = discoverNestedRepositories(projectRoot, { ...config.map, includeNested: true }, workspace).map((repository) => summarizeRepository(projectRoot, repository));
+    const issues = repositories.length === 0
+        ? [t('en', 'workspace.scan.issue.noneDiscovered', { projectsDir })]
+        : [];
+    return {
+        schema_version: WORKSPACE_SCAN_SCHEMA_VERSION,
+        command: 'workspace scan',
+        mustflow_root: projectRoot,
+        workspace: workspaceConfigOutput(workspace),
         policy: createWorkspaceStatusPolicy(),
         repository_count: repositories.length,
         repositories,
         issues,
+        projects_dir: projectsDir,
+        next_actions: [
+            'mf init inside one target repository',
+            'mf workspace status --json after configuring workspace roots',
+        ],
     };
 }
 function readWorkspaceRepositories(projectRoot) {
@@ -171,12 +212,12 @@ function readWorkspaceRepositories(projectRoot) {
 }
 function workspaceConfigOutput(config) {
     return {
-        enabled: config.workspace.enabled,
-        roots: config.workspace.roots,
-        max_depth: config.workspace.maxDepth,
-        max_repositories: config.workspace.maxRepositories,
-        follow_symlinks: config.workspace.followSymlinks,
-        stop_at_repository_root: config.workspace.stopAtRepositoryRoot,
+        enabled: config.enabled,
+        roots: config.roots,
+        max_depth: config.maxDepth,
+        max_repositories: config.maxRepositories,
+        follow_symlinks: config.followSymlinks,
+        stop_at_repository_root: config.stopAtRepositoryRoot,
     };
 }
 function createWorkspaceIssues(config, repositoryCount) {
@@ -295,7 +336,7 @@ function createWorkspaceCommandCatalogOutput() {
         schema_version: WORKSPACE_COMMAND_CATALOG_SCHEMA_VERSION,
         command: 'workspace command-catalog',
         mustflow_root: projectRoot,
-        workspace: workspaceConfigOutput(config),
+        workspace: workspaceConfigOutput(config.workspace),
         policy: createWorkspaceStatusPolicy(),
         repository_count: repositories.length,
         total_intent_count: repositories.reduce((total, repository) => total + repository.intent_count, 0),
@@ -331,6 +372,13 @@ function selectedIntentsForVerificationReport(repositoryPath, report) {
         conflict_count: entry.conflicts.length,
     }));
 }
+/**
+ * mf:anchor cli.workspace.verify-plan
+ * purpose: Build per-repository verification plans from each child repository's own command contract.
+ * search: workspace verify, changed files, plan only, command contract, child repository
+ * invariant: Workspace verification output selects intents per repository and does not run raw commands from the parent root.
+ * risk: config, state
+ */
 function createVerificationRepository(projectRoot, repository) {
     const repositoryRoot = path.resolve(projectRoot, repository.relativePath);
     const commandSurface = summarizeCommandSurface(repositoryRoot, repository);
@@ -391,7 +439,7 @@ function createWorkspaceVerificationPlanOutput() {
         schema_version: WORKSPACE_VERIFICATION_PLAN_SCHEMA_VERSION,
         command: 'workspace verify',
         mustflow_root: projectRoot,
-        workspace: workspaceConfigOutput(config),
+        workspace: workspaceConfigOutput(config.workspace),
         policy: createWorkspaceVerificationPlanPolicy(),
         repository_count: repositories.length,
         total_changed_file_count: repositories.reduce((total, repository) => total + (repository.changed_file_count ?? 0), 0),
@@ -402,6 +450,29 @@ function createWorkspaceVerificationPlanOutput() {
         issues: createWorkspaceIssues(config, repositories.length),
     };
 }
+function renderWorkspaceScan(output) {
+    const lines = [
+        'mustflow workspace scan',
+        `mustflow root: ${output.mustflow_root}`,
+        `projects dir: ${output.projects_dir}`,
+        `repositories: ${output.repository_count}`,
+        '',
+    ];
+    if (output.repositories.length === 0) {
+        lines.push(`No nested repositories discovered under ${output.projects_dir}.`);
+        return lines.join('\n');
+    }
+    for (const repository of output.repositories) {
+        lines.push(`- ${repository.relative_path} (${repository.status})`);
+        lines.push(`  mustflow: ${repository.mustflow ? 'yes' : 'no'}`);
+        lines.push(`  command contract: ${repository.command_contract.path ?? 'missing'}`);
+    }
+    lines.push('', 'Next actions:');
+    for (const action of output.next_actions) {
+        lines.push(`- ${action}`);
+    }
+    return lines.join('\n');
+}
 function renderWorkspaceStatus(output) {
     const lines = [
         'mustflow workspace status',
@@ -488,6 +559,22 @@ function renderWorkspaceVerificationPlan(output) {
     }
     return lines.join('\n');
 }
+function runWorkspaceScan(args, reporter, lang) {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getWorkspaceHelp(lang));
+        return 0;
+    }
+    const parsed = parseCliOptions(args, WORKSPACE_SCAN_OPTIONS);
+    if (parsed.error) {
+        printUsageError(reporter, formatCliOptionParseError(parsed.error, lang), 'mf workspace --help', getWorkspaceHelp(lang), lang);
+        return 1;
+    }
+    const projectsDirValue = parsed.values.get('--projects-dir');
+    const projectsDir = typeof projectsDirValue === 'string' ? projectsDirValue : DEFAULT_WORKSPACE_SCAN_ROOT;
+    const output = createWorkspaceScanOutput(projectsDir);
+    reporter.stdout(hasParsedCliOption(parsed, '--json') ? JSON.stringify(output, null, 2) : renderWorkspaceScan(output));
+    return 0;
+}
 function runWorkspaceStatus(args, reporter, lang) {
     if (hasCliOptionToken(args, '--help', ['-h'])) {
         reporter.stdout(getWorkspaceHelp(lang));
@@ -552,6 +639,9 @@ export function runWorkspace(args, reporter, lang = 'en') {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: action }), 'mf workspace --help', getWorkspaceHelp(lang), lang);
         return 1;
     }
+    if (action === 'scan') {
+        return runWorkspaceScan(rest, reporter, lang);
+    }
     if (action === 'status') {
         return runWorkspaceStatus(rest, reporter, lang);
     }

package/dist/cli/i18n/en.js

@@ -135,14 +135,17 @@ export const enMessages = {
     "evidence.section.gaps": "Gaps",
     "evidence.section.remainingRisks": "Remaining risks",
     "workspace.help.summary": "Inspect configured workspace roots and nested repository contract readiness without granting command authority.",
+    "workspace.help.action.scan": "Scan a projects directory for nested repositories without requiring workspace configuration",
     "workspace.help.action.status": "Print discovered nested repositories and their local mustflow contract status",
     "workspace.help.action.commandCatalog": "Print per-repository command intent availability without raw command strings",
     "workspace.help.action.verify": "Print per-repository changed-file verification plans without running commands",
+    "workspace.help.option.projectsDir": "Select the child directory to scan; default: projects",
     "workspace.help.exit.ok": "Workspace status was inspected",
-    "workspace.error.missingAction": "Specify a workspace action: status, command-catalog, or verify",
+    "workspace.error.missingAction": "Specify a workspace action: scan, status, command-catalog, or verify",
     "workspace.error.unknownAction": "Unknown workspace action: {action}",
     "workspace.error.verifyRequiresChanged": "workspace verify requires --changed",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify requires --plan-only",
+    "workspace.scan.issue.noneDiscovered": "No nested git repositories were discovered under {projectsDir}.",
     "context.help.summary": "Print the agent context for the current mustflow root.",
     "context.help.option.json": "Print machine-readable context JSON",
     "context.help.option.cacheProfile": "Print a prompt-cache profile: stable, task, volatile, or all",
@@ -680,6 +683,8 @@ Read these files before working:
     "init.error.unsupportedPreference": "Unsupported init preference setting: {key}",
     "init.error.promptInputTooLarge": "Interactive init stdin input is too large; expected at most {maxBytes} bytes.",
     "init.error.promptInputTooManyResponses": "Interactive init stdin input has too many responses; expected at most {maxResponses} lines.",
+    "init.error.workspaceRootDetected": "This directory looks like a multi-repository workspace, not a single repository: found {count} git repositories under {projectsDir}.",
+    "init.error.workspaceRootGuidance": "Run mf workspace scan --json here, or run mf init inside one target repository.",
     "init.prompt.locale": "Which language should mustflow documents use?",
     "init.prompt.profile": "Which project profile should mustflow use?",
     "init.prompt.agentLang": "Which language should agents use for final reports?",

package/dist/cli/i18n/es.js

@@ -135,14 +135,17 @@ export const esMessages = {
     "evidence.section.gaps": "Brechas",
     "evidence.section.remainingRisks": "Riesgos restantes",
     "workspace.help.summary": "Inspecciona raíces workspace configuradas y preparación de contratos anidados sin conceder autoridad de comandos.",
+    "workspace.help.action.scan": "Escanea un directorio projects en busca de repositorios anidados sin requerir configuración de workspace",
     "workspace.help.action.status": "Imprime repositorios anidados descubiertos y su estado de contrato mustflow local",
     "workspace.help.action.commandCatalog": "Imprime disponibilidad de intents por repositorio sin cadenas de comando sin procesar",
     "workspace.help.action.verify": "Imprime planes de verificación de cambios por repositorio sin ejecutar comandos",
+    "workspace.help.option.projectsDir": "Selecciona el directorio hijo que se escaneará; predeterminado: projects",
     "workspace.help.exit.ok": "Se inspeccionó el estado del workspace",
-    "workspace.error.missingAction": "Especifica una acción workspace: status, command-catalog o verify",
+    "workspace.error.missingAction": "Especifica una acción workspace: scan, status, command-catalog o verify",
     "workspace.error.unknownAction": "Acción workspace desconocida: {action}",
     "workspace.error.verifyRequiresChanged": "workspace verify requiere --changed",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify requiere --plan-only",
+    "workspace.scan.issue.noneDiscovered": "No se descubrieron repositorios git anidados bajo {projectsDir}.",
     "context.help.summary": "Imprime el contexto de agente para la raíz mustflow actual.",
     "context.help.option.json": "Imprime JSON de contexto legible por máquinas",
     "context.help.option.cacheProfile": "Imprime un perfil de caché de prompt: stable, task, volatile o all",
@@ -680,6 +683,8 @@ Lee estos archivos antes de trabajar:
     "init.error.unsupportedPreference": "Ajuste de preferencia de inicio no admitido: {key}",
     "init.error.promptInputTooLarge": "La entrada estándar de init interactivo es demasiado grande; se esperaban como máximo {maxBytes} bytes.",
     "init.error.promptInputTooManyResponses": "La entrada estándar de init interactivo tiene demasiadas respuestas; se esperaban como máximo {maxResponses} líneas.",
+    "init.error.workspaceRootDetected": "Este directorio parece un workspace de varios repositorios, no un solo repositorio: se encontraron {count} repositorios git bajo {projectsDir}.",
+    "init.error.workspaceRootGuidance": "Ejecuta mf workspace scan --json aquí, o ejecuta mf init dentro de un repositorio de destino.",
     "init.prompt.locale": "¿Qué idioma deben usar los documentos mustflow?",
     "init.prompt.profile": "¿Qué perfil de proyecto debe usar mustflow?",
     "init.prompt.agentLang": "¿Qué idioma deben usar los agentes en los informes finales?",

package/dist/cli/i18n/fr.js

@@ -135,14 +135,17 @@ export const frMessages = {
     "evidence.section.gaps": "Écarts",
     "evidence.section.remainingRisks": "Risques restants",
     "workspace.help.summary": "Inspecte les racines workspace configurées et l'état des contrats imbriqués sans accorder d'autorité de commande.",
+    "workspace.help.action.scan": "Scanne un répertoire projects pour trouver des dépôts imbriqués sans exiger de configuration workspace",
     "workspace.help.action.status": "Affiche les dépôts imbriqués découverts et leur état de contrat mustflow local",
     "workspace.help.action.commandCatalog": "Affiche la disponibilité des intents par dépôt sans chaînes de commande brutes",
     "workspace.help.action.verify": "Affiche les plans de vérification des changements par dépôt sans exécuter de commandes",
+    "workspace.help.option.projectsDir": "Sélectionne le répertoire enfant à scanner ; par défaut : projects",
     "workspace.help.exit.ok": "L'état du workspace a été inspecté",
-    "workspace.error.missingAction": "Indiquez une action workspace : status, command-catalog ou verify",
+    "workspace.error.missingAction": "Indiquez une action workspace : scan, status, command-catalog ou verify",
     "workspace.error.unknownAction": "Action workspace inconnue : {action}",
     "workspace.error.verifyRequiresChanged": "workspace verify nécessite --changed",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify nécessite --plan-only",
+    "workspace.scan.issue.noneDiscovered": "Aucun dépôt git imbriqué n'a été découvert sous {projectsDir}.",
     "context.help.summary": "Imprime le contexte d'agent pour la racine mustflow actuelle.",
     "context.help.option.json": "Imprime le JSON de contexte lisible par machine",
     "context.help.option.cacheProfile": "Imprime un profil de cache de prompt : stable, task, volatile ou all",
@@ -680,6 +683,8 @@ Lisez ces fichiers avant de travailler :
     "init.error.unsupportedPreference": "Paramètre de préférence d'initialisation non pris en charge : {key}",
     "init.error.promptInputTooLarge": "L'entrée standard de l'init interactif est trop volumineuse ; {maxBytes} octets maximum sont attendus.",
     "init.error.promptInputTooManyResponses": "L'entrée standard de l'init interactif contient trop de réponses ; {maxResponses} lignes maximum sont attendues.",
+    "init.error.workspaceRootDetected": "Ce répertoire ressemble à un workspace multi-dépôts, pas à un dépôt unique : {count} dépôts git ont été trouvés sous {projectsDir}.",
+    "init.error.workspaceRootGuidance": "Exécutez mf workspace scan --json ici, ou exécutez mf init dans un dépôt cible.",
     "init.prompt.locale": "Quelle langue les documents mustflow doivent-ils utiliser ?",
     "init.prompt.profile": "Quel profil de projet mustflow doit-il utiliser ?",
     "init.prompt.agentLang": "Quelle langue les agents doivent-ils utiliser pour les rapports finaux ?",

package/dist/cli/i18n/hi.js

@@ -135,14 +135,17 @@ export const hiMessages = {
     "evidence.section.gaps": "Gaps",
     "evidence.section.remainingRisks": "Remaining risks",
     "workspace.help.summary": "command authority दिए बिना configured workspace roots और nested repository contract readiness inspect करें.",
+    "workspace.help.action.scan": "workspace configuration के बिना projects directory में nested repositories scan करें",
     "workspace.help.action.status": "discovered nested repositories और उनके local mustflow contract status प्रिंट करें",
     "workspace.help.action.commandCatalog": "raw command strings के बिना per-repository command intent availability प्रिंट करें",
     "workspace.help.action.verify": "commands चलाए बिना per-repository changed-file verification plans प्रिंट करें",
+    "workspace.help.option.projectsDir": "scan की जाने वाली child directory चुनें; default: projects",
     "workspace.help.exit.ok": "Workspace status inspect हुआ",
-    "workspace.error.missingAction": "workspace action बताएँ: status, command-catalog या verify",
+    "workspace.error.missingAction": "workspace action बताएँ: scan, status, command-catalog या verify",
     "workspace.error.unknownAction": "अज्ञात workspace action: {action}",
     "workspace.error.verifyRequiresChanged": "workspace verify के लिए --changed चाहिए",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify के लिए --plan-only चाहिए",
+    "workspace.scan.issue.noneDiscovered": "{projectsDir} के नीचे कोई nested git repository नहीं मिला.",
     "context.help.summary": "वर्तमान mustflow रूट के लिए एजेंट संदर्भ प्रिंट करें।",
     "context.help.option.json": "मशीन-पठनीय संदर्भ JSON प्रिंट करें",
     "context.help.option.cacheProfile": "prompt cache profile प्रिंट करें: stable, task, volatile, या all",
@@ -680,6 +683,8 @@ export const hiMessages = {
     "init.error.unsupportedPreference": "असमर्थित init preference setting: {key}",
     "init.error.promptInputTooLarge": "Interactive init stdin input बहुत बड़ा है; अधिकतम {maxBytes} bytes अपेक्षित हैं।",
     "init.error.promptInputTooManyResponses": "Interactive init stdin input में बहुत अधिक responses हैं; अधिकतम {maxResponses} lines अपेक्षित हैं।",
+    "init.error.workspaceRootDetected": "यह directory single repository नहीं बल्कि multi-repository workspace जैसी दिखती है: {projectsDir} के नीचे {count} git repositories मिले.",
+    "init.error.workspaceRootGuidance": "यहाँ mf workspace scan --json चलाएँ, या target repository के अंदर mf init चलाएँ.",
     "init.prompt.locale": "mustflow दस्तावेज़ कौन सी भाषा उपयोग करें?",
     "init.prompt.profile": "mustflow कौन सा project profile उपयोग करे?",
     "init.prompt.agentLang": "एजेंट final reports के लिए कौन सी भाषा उपयोग करें?",

package/dist/cli/i18n/ko.js

@@ -135,14 +135,17 @@ export const koMessages = {
     "evidence.section.gaps": "구멍",
     "evidence.section.remainingRisks": "남은 리스크",
     "workspace.help.summary": "명령 권한을 부여하지 않고 설정된 workspace root와 nested repository 계약 준비 상태를 확인합니다.",
+    "workspace.help.action.scan": "workspace 설정 없이 projects 디렉터리의 nested repository를 스캔합니다",
     "workspace.help.action.status": "발견된 nested repository와 각 로컬 mustflow 계약 상태를 출력합니다",
     "workspace.help.action.commandCatalog": "raw command string 없이 repository별 command intent 사용 가능 상태를 출력합니다",
     "workspace.help.action.verify": "명령을 실행하지 않고 repository별 changed-file verification plan을 출력합니다",
+    "workspace.help.option.projectsDir": "스캔할 하위 디렉터리를 지정합니다. 기본값: projects",
     "workspace.help.exit.ok": "workspace 상태를 확인했습니다",
-    "workspace.error.missingAction": "workspace 작업을 지정하세요: status, command-catalog 또는 verify",
+    "workspace.error.missingAction": "workspace 작업을 지정하세요: scan, status, command-catalog 또는 verify",
     "workspace.error.unknownAction": "알 수 없는 workspace 작업: {action}",
     "workspace.error.verifyRequiresChanged": "workspace verify에는 --changed가 필요합니다",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify에는 --plan-only가 필요합니다",
+    "workspace.scan.issue.noneDiscovered": "{projectsDir} 아래에서 nested git repository를 찾지 못했습니다.",
     "context.help.summary": "현재 mustflow 루트의 에이전트 작업 맥락을 출력합니다.",
     "context.help.option.json": "맥락을 JSON 형식으로 출력합니다",
     "context.help.option.cacheProfile": "프롬프트 캐시 프로필을 출력합니다: stable, task, volatile, all",
@@ -680,6 +683,8 @@ export const koMessages = {
     "init.error.unsupportedPreference": "지원하지 않는 초기 설정 항목입니다: {key}",
     "init.error.promptInputTooLarge": "대화형 init 표준입력이 너무 큽니다. 최대 {maxBytes}바이트까지만 허용됩니다.",
     "init.error.promptInputTooManyResponses": "대화형 init 표준입력 응답이 너무 많습니다. 최대 {maxResponses}줄까지만 허용됩니다.",
+    "init.error.workspaceRootDetected": "이 디렉터리는 단일 저장소가 아니라 여러 저장소를 담은 workspace처럼 보입니다: {projectsDir} 아래에서 git repository {count}개를 찾았습니다.",
+    "init.error.workspaceRootGuidance": "여기서는 mf workspace scan --json을 실행하거나, 대상 저장소 안으로 이동해서 mf init을 실행하세요.",
     "init.prompt.locale": "mustflow 문서는 어떤 언어로 설치할까요?",
     "init.prompt.profile": "이 저장소에는 어떤 프로젝트 유형을 사용할까요?",
     "init.prompt.agentLang": "에이전트 최종 응답은 어떤 언어로 받을까요?",

package/dist/cli/i18n/zh.js

@@ -135,14 +135,17 @@ export const zhMessages = {
     "evidence.section.gaps": "缺口",
     "evidence.section.remainingRisks": "剩余风险",
     "workspace.help.summary": "检查已配置的 workspace 根目录和嵌套仓库合同状态，但不授予命令权限。",
+    "workspace.help.action.scan": "无需 workspace 配置即可扫描 projects 目录中的嵌套仓库",
     "workspace.help.action.status": "输出发现的嵌套仓库及其本地 mustflow 合同状态",
     "workspace.help.action.commandCatalog": "输出各仓库的命令 intent 可用性，不包含原始命令字符串",
     "workspace.help.action.verify": "输出各仓库的变更文件验证计划，但不运行命令",
+    "workspace.help.option.projectsDir": "选择要扫描的子目录；默认值：projects",
     "workspace.help.exit.ok": "已检查 workspace 状态",
-    "workspace.error.missingAction": "请指定 workspace 操作：status、command-catalog 或 verify",
+    "workspace.error.missingAction": "请指定 workspace 操作：scan、status、command-catalog 或 verify",
     "workspace.error.unknownAction": "未知 workspace 操作：{action}",
     "workspace.error.verifyRequiresChanged": "workspace verify 需要 --changed",
     "workspace.error.verifyRequiresPlanOnly": "workspace verify 需要 --plan-only",
+    "workspace.scan.issue.noneDiscovered": "未在 {projectsDir} 下发现嵌套 git 仓库。",
     "context.help.summary": "输出当前 mustflow 根目录的代理上下文。",
     "context.help.option.json": "输出机器可读的上下文 JSON",
     "context.help.option.cacheProfile": "输出提示缓存配置文件：stable、task、volatile 或 all",
@@ -680,6 +683,8 @@ export const zhMessages = {
     "init.error.unsupportedPreference": "不支持的初始化偏好设置：{key}",
     "init.error.promptInputTooLarge": "交互式 init 的标准输入过大；最多允许 {maxBytes} 字节。",
     "init.error.promptInputTooManyResponses": "交互式 init 的标准输入响应过多；最多允许 {maxResponses} 行。",
+    "init.error.workspaceRootDetected": "此目录看起来是多仓库 workspace，而不是单个仓库：在 {projectsDir} 下发现了 {count} 个 git 仓库。",
+    "init.error.workspaceRootGuidance": "请在此处运行 mf workspace scan --json，或进入目标仓库后运行 mf init。",
     "init.prompt.locale": "mustflow 文档应使用哪种语言？",
     "init.prompt.profile": "mustflow 应使用哪个项目配置？",
     "init.prompt.agentLang": "代理最终报告应使用哪种语言？",

package/dist/cli/index.js

@@ -40,6 +40,7 @@ function getTopLevelHelp(lang) {
             'mf onboard commands --json',
             'mf next --json',
             'mf evidence --changed --json',
+            'mf workspace scan --json',
             'mf workspace status --json',
             'mf workspace verify --changed --plan-only --json',
             'mf context --json',
@@ -99,6 +100,13 @@ function parseGlobalOptions(argv) {
     }
     return { lang, args: parsed.positionals };
 }
+/**
+ * mf:anchor cli.entrypoint.dispatch
+ * purpose: Resolve top-level CLI options and dispatch commands without bypassing per-command validation.
+ * search: CLI dispatch, global options, command registry, version alias, help
+ * invariant: Unknown commands and global option errors must stop before any command runner is loaded.
+ * risk: config
+ */
 export async function runCli(argv, reporter = consoleReporter) {
     const parsed = parseGlobalOptions(argv);
     const [command, ...args] = parsed.args;

package/dist/cli/lib/agent-context.js

@@ -598,6 +598,13 @@ function readTaskPromptCacheRepoMapReadPlan() {
         },
     };
 }
+/**
+ * mf:anchor cli.context.prompt-cache-task-layer
+ * purpose: Build the task-layer context plan that prefers selected routes, local-index anchors, and bounded repo-map spans.
+ * search: mf context, prompt cache, task context, route read plan, repo map, local index
+ * invariant: Task context may recommend what to read next but cannot replace AGENTS.md or command contract authority.
+ * risk: config, cache
+ */
 async function readTaskPromptCacheLayer(projectRoot, mustflow) {
     const layer = readPromptCacheLayer(mustflow, 'task');
     const localIndex = await readLocalIndexPromptContext(projectRoot);