mustflow 1.30.0 → 2.11.0

package/README.md

@@ -2,9 +2,9 @@
 
 Languages: [English](README.md) · [한국어](docs/i18n/ko/README.md) · [中文](docs/i18n/zh/README.md) · [Español](docs/i18n/es/README.md) · [Français](docs/i18n/fr/README.md) · [हिन्दी](docs/i18n/hi/README.md)
 
-mustflow is a workflow CLI designed for LLM coding agents. It guides agents to enter a repository, understand the correct operating context, run only authorized commands, and verify their work without guessing.
+mustflow is a repository-local work contract and verification CLI for LLM coding agents. It keeps agents inside explicit read, command, and verification boundaries without replacing the host agent's sandbox, approval, checkpoint, model, or tool policies.
 
-The core concept is straightforward: place `AGENTS.md` at the project root and keep detailed workflows under `.mustflow/`. Agents start from `AGENTS.md` and then follow the command contract, skills, project context, and verification rules in sequence.
+The core concept is straightforward: place `AGENTS.md` at the project root and keep detailed workflows under `.mustflow/`. Agents start from `AGENTS.md`, then follow the repository command contract, skills, project context, and verification rules in sequence.
 
 - Documentation site: <https://0disoft.github.io/mustflow/>
 - Human-readable project examples: [`examples/`](examples/)
@@ -14,10 +14,24 @@ The core concept is straightforward: place `AGENTS.md` at the project root and k
 - Security: [SECURITY.md](https://github.com/0disoft/mustflow/blob/main/SECURITY.md)
 - Changelog: [CHANGELOG.md](https://github.com/0disoft/mustflow/blob/main/CHANGELOG.md)
 
+## Choose your path
+
+- Use mustflow in your repository: start with [Quick start](#quick-start), then review the [no-guessing workflow](#no-guessing-workflow) and [`examples/minimal-js/`](examples/minimal-js/).
+- Contribute to mustflow: read [CONTRIBUTING.md](CONTRIBUTING.md), then run only configured command intents from [`.mustflow/config/commands.toml`](.mustflow/config/commands.toml).
+- Build an AI coding tool or agent harness: use `AGENTS.md` and `mf context --json` for repository context, then consume JSON output and schemas from `mf classify`, `mf verify`, `mf run`, `mf dashboard`, and [`schemas/`](schemas/).
+
 ## No-guessing workflow
 
 The initial mustflow path is deliberately narrow.
 
+Authority stays narrow:
+
+- Current user instructions define the task goal unless they are unsafe.
+- Host safety, sandbox, and approval gates still apply.
+- Repository work rules come from the nearest `AGENTS.md` and `.mustflow/config/*.toml`.
+- Command execution authority comes only from `.mustflow/config/commands.toml`.
+- Skills, context files, preferences, generated maps, search results, cache, and state files guide or explain work. They do not grant command permission.
+
 ```sh
 npm install -D mustflow
 npx mf init --yes
@@ -27,9 +41,9 @@ npx mf check --strict
 After changes to code, templates, schemas, or documentation, classify the changed paths and review the verification plan before running any commands.
 
 ```sh
-npx mf classify --changed --json > .mustflow/state/change-plan.json
-npx mf verify --from-plan .mustflow/state/change-plan.json --plan-only --json
-npx mf verify --from-plan .mustflow/state/change-plan.json --json
+npx mf classify --changed --write .mustflow/state/change-classification.json
+npx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json
+npx mf verify --from-classification .mustflow/state/change-classification.json --json
 ```
 
 The plan is based on change classification and the `required_after` metadata in `.mustflow/config/commands.toml`. A command runs only if its declared intent is configured, one-shot, agent-allowed, closed-stdin, bounded by a timeout, and backed by an explicit command source.
@@ -239,9 +253,9 @@ If a project already has optional root Markdown files such as `README.md`, `PROJ
 npx mf init --yes
 npx mf doctor
 npx mf check --strict
-npx mf classify --changed --json > .mustflow/state/change-plan.json
-npx mf verify --from-plan .mustflow/state/change-plan.json --plan-only --json
-npx mf verify --from-plan .mustflow/state/change-plan.json --json
+npx mf classify --changed --write .mustflow/state/change-classification.json
+npx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json
+npx mf verify --from-classification .mustflow/state/change-classification.json --json
 ```
 
 Create the optional local search index if search capabilities are needed. Run the normal command
@@ -268,6 +282,14 @@ npx mf update --dry-run
 npx mf update --apply
 ```
 
+After updating the mustflow package, `mf upgrade` combines the package freshness check with the safe project-file update step. It does not install packages by itself; update npm, pnpm, or Bun first.
+
+```sh
+bun update -g mustflow
+mf upgrade --dry-run
+mf upgrade
+```
+
 Agents should prefer the configured update intents so the repository receives a run receipt.
 
 ```sh
@@ -286,8 +308,8 @@ mf run mustflow_update_apply
 | `mf check` | Validate mustflow files, TOML configuration, and skill document shape. |
 | `mf check --strict` | Run additional safety checks for document identity, authority/lifecycle metadata, skill index/body alignment, skill metadata, command boundaries, version-source discovery, retention policy, output limits, raw logs, and secret-like context. |
 | `mf adapters status` | Inspect existing host-specific instruction and adapter files without generating adapter files or granting command authority. |
-| `mf classify --changed` | Classify changed paths, public surfaces, and validation reasons without modifying files. |
-| `mf contract-lint` | Inspect `.mustflow/config/commands.toml` for command-contract errors and warnings without running commands. |
+| `mf classify --changed` | Classify changed paths, public surfaces, and validation reasons. Add `--write <path>` to save the classification report. |
+| `mf contract-lint` | Inspect `.mustflow/config/commands.toml` for command-contract errors and warnings without running commands. Add `--suggest` to print non-runnable candidate snippets from existing command files. |
 | `mf doctor` | Inspect the current mustflow root without writing files. |
 | `mf docs review list` | Show documents still waiting for prose review after agent edits. |
 | `mf docs review add <path>` | Add or refresh a document review queue entry. |
@@ -304,6 +326,8 @@ mf run mustflow_update_apply
 | `mf status` | Inspect installed state and changed or missing files. |
 | `mf update --dry-run` | Calculate a template update plan without writing files. |
 | `mf update --apply` | Apply template updates when nothing is blocked. |
+| `mf upgrade` | Check package freshness, then apply safe bundled template updates when the package is current. |
+| `mf upgrade --dry-run` | Check package freshness and print the safe project update plan without writing files. |
 | `mf help <topic>` | Show installed mustflow help. |
 | `mf dashboard` | Start a local inspection dashboard for status, verification recommendations, release/version-source status, template update readiness, latest run receipt, skill routes, safe preferences, and documentation review. Use `--export-json <path>` or `--export <path>` for a bounded static report. It does not execute commands or apply fixes. |
 | `mf version` | Print the installed mustflow package version. |
@@ -346,7 +370,7 @@ npx mf init --product-source-locale en --product-locale ko-KR
 npx mf init --set git.auto_commit=true
 ```
 
-- `--profile`: Project profile. The default is `minimal`. Profiles also select the installed skill surface: `minimal` installs core everyday coding skills, while `oss`, `team`, `product`, and `library` add opt-in skill groups without removing optional skill files from the package.
+- `--profile`: Project profile. The default is `minimal`. Profiles also select the installed skill surface: `minimal` installs core everyday coding skills, `patterns` adds architecture-pattern procedures, and `oss`, `team`, `product`, and `library` add opt-in skill groups without removing optional skill files from the package.
 - `--locale`: Installed mustflow document language. The default template currently supports `en`, `ko`, `zh`, `es`, `fr`, and `hi`. The default template includes localized documents for all these locales.
 - `--agent-lang`: Default language for final agent reports.
 - `--interactive`: Choose init settings via prompts.

package/dist/cli/commands/classify.js

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { createChangeClassificationReport, } from '../../core/change-classification.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { readGitChangedFiles } from '../lib/git-changes.js';
@@ -10,10 +12,15 @@ export function getClassifyHelp(lang = 'en') {
         summary: t(lang, 'classify.help.summary'),
         options: [
             { label: '--changed', description: t(lang, 'classify.help.option.changed') },
+            { label: '--write <path>', description: t(lang, 'classify.help.option.write') },
             { label: '--json', description: t(lang, 'cli.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf classify --changed', 'mf classify README.md schemas/verify-report.schema.json --json'],
+        examples: [
+            'mf classify --changed',
+            'mf classify --changed --write .mustflow/state/change-classification.json',
+            'mf classify README.md schemas/verify-report.schema.json --json',
+        ],
         exitCodes: [
             { label: '0', description: t(lang, 'classify.help.exit.ok') },
             { label: '1', description: t(lang, 'cli.common.invalidInput') },
@@ -24,7 +31,9 @@ function parseClassifyArgs(args) {
     const paths = [];
     let json = false;
     let changed = false;
-    for (const arg of args) {
+    let writePath;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
         if (arg === '--json') {
             json = true;
             continue;
@@ -33,12 +42,29 @@ function parseClassifyArgs(args) {
             changed = true;
             continue;
         }
+        if (arg === '--write') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                return { json, changed, writePath, paths, error: 'missing_write_value' };
+            }
+            writePath = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--write=')) {
+            const value = arg.slice('--write='.length);
+            if (value.length === 0) {
+                return { json, changed, writePath, paths, error: 'missing_write_value' };
+            }
+            writePath = value;
+            continue;
+        }
         if (arg.startsWith('-')) {
-            return { json, changed, paths, error: arg };
+            return { json, changed, writePath, paths, error: arg };
         }
         paths.push(arg);
     }
-    return { json, changed, paths };
+    return { json, changed, writePath, paths };
 }
 export function createClassifyOutput(projectRoot, source, paths) {
     const files = source === 'changed' ? readGitChangedFiles(projectRoot) : paths;
@@ -75,6 +101,19 @@ function renderClassifyOutput(output, lang) {
     }
     return lines.join('\n');
 }
+function resolveWritePath(projectRoot, inputPath) {
+    const resolved = path.resolve(projectRoot, inputPath);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('write_path_outside_root');
+    }
+    return resolved;
+}
+function writeClassifyOutput(projectRoot, inputPath, output) {
+    const outputPath = resolveWritePath(projectRoot, inputPath);
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, `${JSON.stringify(output, null, 2)}\n`, 'utf8');
+}
 export function runClassify(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getClassifyHelp(lang));
@@ -82,7 +121,10 @@ export function runClassify(args, reporter, lang = 'en') {
     }
     const parsed = parseClassifyArgs(args);
     if (parsed.error) {
-        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: parsed.error }), 'mf classify --help', getClassifyHelp(lang), lang);
+        const message = parsed.error === 'missing_write_value'
+            ? t(lang, 'cli.error.missingValue', { option: '--write' })
+            : t(lang, 'cli.error.unknownOption', { option: parsed.error });
+        printUsageError(reporter, message, 'mf classify --help', getClassifyHelp(lang), lang);
         return 1;
     }
     if (parsed.changed && parsed.paths.length > 0) {
@@ -93,7 +135,20 @@ export function runClassify(args, reporter, lang = 'en') {
         printUsageError(reporter, t(lang, 'classify.error.missingInput'), 'mf classify --help', getClassifyHelp(lang), lang);
         return 1;
     }
-    const output = createClassifyOutput(resolveMustflowRoot(), parsed.changed ? 'changed' : 'paths', parsed.paths);
+    const projectRoot = resolveMustflowRoot();
+    const output = createClassifyOutput(projectRoot, parsed.changed ? 'changed' : 'paths', parsed.paths);
+    if (parsed.writePath) {
+        try {
+            writeClassifyOutput(projectRoot, parsed.writePath, output);
+        }
+        catch (error) {
+            const message = error instanceof Error && error.message === 'write_path_outside_root'
+                ? t(lang, 'classify.error.write_path_outside_root')
+                : t(lang, 'cli.common.invalidInput');
+            printUsageError(reporter, message, 'mf classify --help', getClassifyHelp(lang), lang);
+            return 1;
+        }
+    }
     if (parsed.json) {
         reporter.stdout(JSON.stringify(output, null, 2));
         return 0;

package/dist/cli/commands/contract-lint.js

@@ -14,10 +14,11 @@ export function getContractLintHelp(lang = 'en') {
         summary: t(lang, 'contractLint.help.summary'),
         options: [
             { label: '--coverage', description: t(lang, 'contractLint.help.option.coverage') },
+            { label: '--suggest', description: t(lang, 'contractLint.help.option.suggest') },
             { label: '--json', description: t(lang, 'cli.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf contract-lint', 'mf contract-lint --coverage', 'mf contract-lint --coverage --json'],
+        examples: ['mf contract-lint', 'mf contract-lint --coverage', 'mf contract-lint --suggest', 'mf contract-lint --coverage --json'],
         exitCodes: [
             { label: '0', description: t(lang, 'contractLint.help.exit.ok') },
             { label: '1', description: t(lang, 'contractLint.help.exit.fail') },
@@ -32,13 +33,14 @@ function readPreferences(projectRoot) {
     const preferences = readTomlFile(preferencesPath);
     return isRecord(preferences) ? preferences : undefined;
 }
-function createContractLintOutput(projectRoot, coverage) {
+function createContractLintOutput(projectRoot, coverage, suggest) {
     return {
         schema_version: CONTRACT_LINT_SCHEMA_VERSION,
         command: 'contract-lint',
         mustflow_root: projectRoot,
         report: lintCommandContract(readCommandContract(projectRoot), {
             coverage,
+            suggest,
             projectRoot,
             releaseVersioningEnabled: releaseVersioningIsEnabled(readPreferences(projectRoot)),
         }),
@@ -63,6 +65,13 @@ function renderContractLintOutput(output, lang) {
     if (output.report.coverage) {
         lines.push('', t(lang, 'contractLint.label.coverage'), `${t(lang, 'contractLint.label.classificationReasons')}: ${output.report.coverage.knownClassificationReasons.length}`, `${t(lang, 'contractLint.label.requiredAfterReasons')}: ${output.report.coverage.requiredAfterReasons.length}`, `${t(lang, 'contractLint.label.runnableReasons')}: ${output.report.coverage.runnableReasons.length}`, `${t(lang, 'contractLint.label.coverageFindings')}: ${output.report.coverage.findings.length}`);
     }
+    if (output.report.suggestions) {
+        lines.push('', t(lang, 'contractLint.label.suggestions'));
+        for (const suggestion of output.report.suggestions) {
+            lines.push(`- ${suggestion.sourceFile}:${suggestion.sourceName} -> ${suggestion.suggestedIntent}`);
+            lines.push(...suggestion.snippet.split('\n').map((line) => `  ${line}`));
+        }
+    }
     if (output.report.issues.length > 0) {
         lines.push('', t(lang, 'contractLint.label.issues'));
         for (const issue of output.report.issues) {
@@ -77,13 +86,13 @@ export function runContractLint(args, reporter, lang = 'en') {
         reporter.stdout(getContractLintHelp(lang));
         return 0;
     }
-    const supported = new Set(['--coverage', '--json']);
+    const supported = new Set(['--coverage', '--suggest', '--json']);
     const unsupported = args.filter((arg) => !supported.has(arg));
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf contract-lint --help', getContractLintHelp(lang), lang);
         return 1;
     }
-    const output = createContractLintOutput(resolveMustflowRoot(), args.includes('--coverage'));
+    const output = createContractLintOutput(resolveMustflowRoot(), args.includes('--coverage'), args.includes('--suggest'));
     if (args.includes('--json')) {
         reporter.stdout(JSON.stringify(output, null, 2));
     }

package/dist/cli/commands/dashboard.js

@@ -25,6 +25,7 @@ const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
 const DEFAULT_DASHBOARD_PORT = 0;
 const MAX_REQUEST_BYTES = 64 * 1024;
 const LOCAL_DASHBOARD_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+const DOC_REVIEW_BULK_PAYLOAD_FIELDS = ['paths', 'documents', 'entries'];
 const RELEASE_FILE_PATTERNS = [
     /^package\.json$/u,
     /^bun\.lockb?$/u,
@@ -296,6 +297,11 @@ function readDocReviewPayload(value) {
         throw new Error('Request body must be a JSON object.');
     }
     const payload = value;
+    for (const field of DOC_REVIEW_BULK_PAYLOAD_FIELDS) {
+        if (field in payload) {
+            throw new Error('Bulk documentation review updates require a separate confirmed flow.');
+        }
+    }
     const status = readRequiredStringField(payload, 'status');
     if (status !== 'approved' && status !== 'needs_human' && status !== 'ignored') {
         throw new Error('status must be approved, needs_human, or ignored.');

package/dist/cli/commands/index.js

@@ -42,6 +42,11 @@ function renderIndexSummary(result, lang) {
         `skill_routes: ${result.skill_route_count}`,
         `${t(lang, 'label.commandIntents')}: ${result.command_intent_count}`,
         `command_effects: ${result.command_effect_count}`,
+        `verification_evidence_summaries: ${result.verification_evidence_summary_count}`,
+        `verification_receipt_summaries: ${result.verification_receipt_summary_count}`,
+        `verification_coverage_states: ${result.verification_coverage_state_count}`,
+        `verification_risk_signals: ${result.verification_risk_signal_count}`,
+        `failure_fingerprints: ${result.failure_fingerprint_count}`,
         `source_anchors: ${result.source_anchor_count}`,
         `index_mode: ${result.index_mode}`,
         `reused_existing: ${result.reused_existing ? 'yes' : 'no'}`,