mustflow 1.15.97

package/dist/core/version-sync-policy.js

@@ -0,0 +1,85 @@
+export const INSTALLED_TEMPLATE_SURFACE_PATHS = [
+    'templates/default/manifest.toml',
+    'templates/default/i18n.toml',
+    'templates/default/common/',
+    'templates/default/locales/',
+];
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//u, '');
+}
+function parseSemverCore(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/u.exec(version.trim());
+    if (!match) {
+        return null;
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareSemver(left, right) {
+    const leftVersion = parseSemverCore(left);
+    const rightVersion = parseSemverCore(right);
+    if (!leftVersion || !rightVersion) {
+        return null;
+    }
+    for (let index = 0; index < leftVersion.length; index += 1) {
+        const difference = leftVersion[index] - rightVersion[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+export function pathTouchesInstalledTemplateSurface(path) {
+    const normalized = normalizePath(path);
+    return INSTALLED_TEMPLATE_SURFACE_PATHS.some((surfacePath) => surfacePath.endsWith('/') ? normalized.startsWith(surfacePath) : normalized === surfacePath);
+}
+function installedTemplateSurfaceChanged(changedPaths) {
+    if (!changedPaths) {
+        return null;
+    }
+    return changedPaths.some(pathTouchesInstalledTemplateSurface);
+}
+export function evaluateVersionSync(input) {
+    const { packageVersion, templateVersion, syncTemplateVersion } = input;
+    const surfaceChanged = installedTemplateSurfaceChanged(input.changedPaths);
+    if (!packageVersion || !templateVersion || packageVersion === templateVersion) {
+        return {
+            issues: [],
+            installedTemplateSurfaceChanged: surfaceChanged,
+        };
+    }
+    const comparison = compareSemver(templateVersion, packageVersion);
+    if (comparison !== null && comparison > 0) {
+        return {
+            issues: [
+                {
+                    severity: 'error',
+                    code: 'template_version_ahead',
+                    message: `templates/default/manifest.toml version "${templateVersion}" must not be ahead of package.json version "${packageVersion}"`,
+                },
+            ],
+            installedTemplateSurfaceChanged: surfaceChanged,
+        };
+    }
+    if (syncTemplateVersion && surfaceChanged !== false) {
+        return {
+            issues: [
+                {
+                    severity: 'error',
+                    code: 'template_version_mismatch',
+                    message: `templates/default/manifest.toml version "${templateVersion}" must match package.json version "${packageVersion}" when [release.versioning].sync_template_version is true`,
+                },
+            ],
+            installedTemplateSurfaceChanged: surfaceChanged,
+        };
+    }
+    return {
+        issues: [
+            {
+                severity: 'warning',
+                code: 'template_version_intentionally_unchanged',
+                message: `templates/default/manifest.toml version "${templateVersion}" is older than package.json version "${packageVersion}"; this is allowed only when the installed template surface is unchanged`,
+            },
+        ],
+        installedTemplateSurfaceChanged: surfaceChanged,
+    };
+}

package/examples/README.md

@@ -0,0 +1,13 @@
+# mustflow Examples
+
+This directory contains human-readable project examples.
+
+These examples are not test fixtures and are not copied by `mf init`. They illustrate the structure of a project before and after integrating mustflow, while excluding generated or template-owned files from the example content.
+
+Current examples:
+
+- `docs-only/`: A documentation-focused repository with explicit checks for missing code.
+- `host-instruction-conflicts/`: A repository where host-specific instructions overlap with mustflow rules.
+- `minimal-js/`: A small JavaScript package before and after adding mustflow.
+- `missing-command-contracts/`: A repository with package scripts that are not yet defined as mustflow command intents.
+- `nested-repos/`: Parent and child repositories with separate local contracts.

package/examples/docs-only/README.md

@@ -0,0 +1,72 @@
+# Documentation-Only Project
+
+This example demonstrates how mustflow can be applied to a repository that primarily contains Markdown documentation and does not include an application build.
+
+## Before
+
+```text
+docs-handbook/
+├─ README.md
+└─ docs/
+   ├─ guide.md
+   └─ release-notes.md
+```
+
+The project contains useful documents but lacks an explicit agent contract for which checks exist. An agent might search for package scripts or attempt to infer a documentation build command that does not exist.
+
+## After
+
+```text
+docs-handbook/
+├─ AGENTS.md
+├─ README.md
+├─ docs/
+│  ├─ guide.md
+│  └─ release-notes.md
+└─ .mustflow/
+   ├─ config/
+   │  ├─ commands.toml
+   │  ├─ mustflow.toml
+   │  └─ preferences.toml
+   ├─ context/
+   │  ├─ INDEX.md
+   │  └─ PROJECT.md
+   ├─ docs/
+   │  └─ agent-workflow.md
+   └─ skills/
+      ├─ INDEX.md
+      └─ ...
+```
+
+The owner can declare that documentation validation is available while explicitly marking missing code checks:
+
+```toml
+[intents.docs_validate_fast]
+status = "configured"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Check documentation links and frontmatter."
+argv = ["node", "scripts/check-docs.mjs"]
+cwd = "."
+timeout_seconds = 60
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["docs_change"]
+
+[intents.build]
+status = "unknown"
+description = "Build the project."
+reason = "This documentation-only repository has no application build."
+agent_action = "do_not_guess_report_missing"
+
+[intents.test]
+status = "unknown"
+description = "Run tests."
+reason = "This documentation-only repository has no test suite."
+agent_action = "do_not_guess_report_missing"
+```
+
+With this contract, an agent can update prose, run the declared documentation check, and report that code build or test checks are intentionally unavailable, rather than treating missing scripts as hidden failures.

package/examples/host-instruction-conflicts/README.md

@@ -0,0 +1,47 @@
+# Host Instruction Conflicts
+
+This example illustrates how mustflow should be interpreted when a coding host also reads its own instruction files.
+
+## Layout
+
+```text
+hosted-project/
+├─ AGENTS.md
+├─ .github/
+│  └─ copilot-instructions.md
+└─ .mustflow/
+   └─ config/
+      └─ commands.toml
+```
+
+`AGENTS.md` and `.mustflow/config/commands.toml` remain the repository-local mustflow contract. Host-specific files may add editor or assistant guidance, but they do not grant command authority on their own.
+
+## Conflict Example
+
+The host file might state:
+
+```md
+Run npm test before every final answer.
+```
+
+If `.mustflow/config/commands.toml` does not declare an agent-allowed `test` intent, the agent should not infer `npm test` from that host file. Instead, it should report the missing command contract.
+
+If the host file says:
+
+```md
+Prefer short final answers.
+```
+
+this can coexist with mustflow because it neither broadens file scope, weakens safety rules, nor authorizes a command.
+
+## Resolution Rule
+
+Apply the stricter, safer interpretation:
+
+- Direct user instructions define the task goal unless they are unsafe.
+- Host safety and approval gates remain in effect.
+- mustflow command execution is governed by `.mustflow/config/commands.toml`.
+- The nearest `AGENTS.md` and `.mustflow/config/*.toml` files define repository work rules.
+- Generated state or cached summaries cannot override current files.
+
+When the effective rule is unclear, stop and report the conflict rather than guessing.

package/examples/minimal-js/README.md

@@ -0,0 +1,98 @@
+# Minimal JavaScript Project
+
+This example demonstrates how a small JavaScript package changes when mustflow is added.
+
+It is intentionally brief. The installed `.mustflow/**` files are summarized here rather than shown in full, since the definitive source is the default template under `templates/default/`.
+
+## Before
+
+```text
+minimal-js/
+├─ package.json
+└─ src/
+   └─ index.js
+```
+
+The project includes standard package scripts but lacks a repository-local agent workflow contract. An agent would need to infer which commands are safe to run.
+
+```json
+{
+  "name": "minimal-js",
+  "type": "module",
+  "scripts": {
+    "build": "node src/index.js",
+    "test": "node --test"
+  }
+}
+```
+
+## After
+
+```text
+minimal-js/
+├─ AGENTS.md
+├─ package.json
+├─ src/
+│  └─ index.js
+└─ .mustflow/
+   ├─ config/
+   │  ├─ commands.toml
+   │  ├─ mustflow.toml
+   │  └─ preferences.toml
+   ├─ context/
+   │  ├─ INDEX.md
+   │  └─ PROJECT.md
+   ├─ docs/
+   │  └─ agent-workflow.md
+   └─ skills/
+      ├─ INDEX.md
+      └─ ...
+```
+
+`AGENTS.md` becomes the first file an agent reads. `.mustflow/config/commands.toml` defines the command contract, so agents run declared intents instead of guessing from `package.json`.
+
+For this project, the owner might configure only the checks that are relevant:
+
+```toml
+[intents.build]
+status = "configured"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Run the package build."
+argv = ["npm", "run", "build"]
+cwd = "."
+timeout_seconds = 30
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["code_change"]
+
+[intents.test]
+status = "configured"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Run the package tests."
+argv = ["npm", "test"]
+cwd = "."
+timeout_seconds = 30
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["code_change", "test_change"]
+```
+
+If a command is not yet defined, it remains explicit rather than inferred:
+
+```toml
+[intents.lint]
+status = "unknown"
+description = "Run linting."
+reason = "This project has not declared a lint command yet."
+agent_action = "do_not_guess_report_missing"
+```
+
+The resulting workflow is minimal: read `AGENTS.md`, select the relevant mustflow context and skills, run only configured one-shot intents, then report which checks were run or skipped.

package/examples/missing-command-contracts/README.md

@@ -0,0 +1,70 @@
+# Missing Command Contracts
+
+This example demonstrates how mustflow handles package scripts that have not been declared as command intents.
+
+## Before
+
+```text
+scripted-project/
+├─ package.json
+└─ src/
+   └─ index.js
+```
+
+The package includes the following scripts:
+
+```json
+{
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "node --test"
+  }
+}
+```
+
+Without mustflow, an agent might assume any script is safe to run. mustflow does not follow this assumption.
+
+## After
+
+```text
+scripted-project/
+├─ AGENTS.md
+├─ package.json
+└─ .mustflow/
+   └─ config/
+      └─ commands.toml
+```
+
+Only command intents that are declared as configured, one-shot, agent-allowed, and closed-stdin are available to agents.
+
+```toml
+[intents.build]
+status = "configured"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Build the package."
+argv = ["npm", "run", "build"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = ["dist/"]
+network = false
+destructive = false
+required_after = ["code_change"]
+
+[intents.lint]
+status = "unknown"
+description = "Run linting."
+reason = "The repository has not declared whether lint is safe for agents."
+agent_action = "do_not_guess_report_missing"
+
+[intents.test]
+status = "manual_only"
+description = "Run tests."
+reason = "The test suite may be slow or require a local service."
+agent_action = "do_not_run_report_manual"
+```
+
+In this configuration, an agent may run `mf run build` for a covered code change, but it must not run `npm run lint` or `npm test` directly. The final report will indicate that lint is missing and tests are manual-only.

package/examples/nested-repos/README.md

@@ -0,0 +1,62 @@
+# Nested Repositories
+
+This example demonstrates how mustflow should be interpreted when one repository contains other repositories that also have mustflow installed.
+
+## Layout
+
+```text
+workspace-a/
+├─ AGENTS.md
+├─ .mustflow/
+│  └─ config/
+│     └─ commands.toml
+└─ repos/
+   ├─ service-b/
+   │  ├─ AGENTS.md
+   │  └─ .mustflow/
+   │     └─ config/
+   │        └─ commands.toml
+   └─ docs-c/
+      ├─ AGENTS.md
+      └─ .mustflow/
+         └─ config/
+            └─ commands.toml
+```
+
+`workspace-a` can define broad workspace conventions, but it does not control the command contract for `repos/service-b` or `repos/docs-c`.
+
+## Working Rule
+
+When an agent edits files within a nested repository, it should reload that repository's nearest `AGENTS.md` and `.mustflow/config/*.toml` files before editing or running commands.
+
+The nearest child repository determines local details such as:
+
+- Commit message language and style preferences
+- Documentation language
+- Available command intents
+- Safe verification commands
+- Project-specific context and skills
+
+Safety rules are cumulative. A child repository can impose stricter behavior for its own files but cannot weaken safety constraints set by the parent, host, user, or platform.
+
+## Example Difference
+
+The parent workspace might allow English commit messages:
+
+```toml
+[git.commit_message]
+language = "en"
+```
+
+The nested documentation repository might prefer Korean commit messages:
+
+```toml
+[git.commit_message]
+language = "ko"
+```
+
+When editing files under `repos/docs-c/**`, the nested repository's preference applies locally. The agent should not use the parent preference simply because the command was initiated from `workspace-a`.
+
+## Command Contract Boundary
+
+If `workspace-a` includes `test_related` but `repos/service-b` does not, the agent must not borrow the parent's command intent to validate changes in the child. Instead, it should use the child repository's configured intents or report the absence of a child command contract.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "mustflow",
+	"version": "1.15.97",
+  "description": "Agent workflow documents and CLI for mustflow repository roots.",
+  "type": "module",
+  "license": "MIT-0",
+  "homepage": "https://0disoft.github.io/mustflow/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0disoft/mustflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0disoft/mustflow/issues"
+  },
+  "packageManager": "bun@1.3.13",
+  "bin": {
+    "mf": "./dist/cli/index.js",
+    "mustflow": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "schemas/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "test": "bun run test:full",
+    "test:fast": "bun run build && node scripts/run-cli-tests.mjs fast",
+    "test:related": "bun run build && node scripts/run-cli-tests.mjs related",
+    "test:cli": "bun run build && node scripts/run-cli-tests.mjs cli",
+    "test:coverage": "bun run build && node scripts/run-cli-tests.mjs coverage",
+    "test:audit": "node scripts/audit-tests.mjs --json",
+    "test:release": "bun run build && node scripts/run-cli-tests.mjs release",
+    "test:full": "bun run build && node scripts/run-cli-tests.mjs full",
+    "check": "bun run check:package && bun run test:full",
+    "check:package": "node -e \"const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json ok')\"",
+    "check:typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "check:pack": "npm pack --dry-run --json",
+    "check:install": "npm run check:pack && node --test tests/integration/*.test.js",
+    "release:check": "npm run check && npm run docs:check && npm run check:install",
+    "prepublishOnly": "npm run release:check",
+    "docs:dev": "bun run --cwd docs-site dev",
+    "docs:build": "bun run --cwd docs-site build",
+    "docs:check:fast": "bun run --cwd docs-site check:fast",
+    "docs:check": "bun run --cwd docs-site check",
+    "docs:preview": "bun run --cwd docs-site preview"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agents",
+    "agents-md",
+    "agent-workflow",
+    "llm",
+    "codex",
+    "mustflow",
+    "repo-map",
+    "repository-template",
+    "toml",
+    "workflow"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@types/sql.js": "^1.4.11",
+    "fast-check": "^4.7.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "smol-toml": "^1.6.1",
+    "sql.js": "^1.14.1"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,32 @@
+# mustflow JSON Schemas
+
+This directory contains versioned JSON Schema contracts for machine-readable  
+mustflow files and command output.
+
+Current schemas:
+
+- `doctor-report.schema.json`: output of `mf doctor --json`
+- `context-report.schema.json`: output of `mf context --json`
+- `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`
+- `commands.schema.json`: parsed `.mustflow/config/commands.toml`
+- `contract-lint-report.schema.json`: output of `mf contract-lint --json`
+- `classify-report.schema.json`: output of `mf classify --changed --json` and  
+  `mf classify <path...> --json`
+- `impact-report.schema.json`: output of `mf impact --changed --json` and  
+  `mf impact <path...> --json`
+- `line-endings-report.schema.json`: output of `mf line-endings check --json` and  
+  `mf line-endings normalize --json`
+- `version-sources-report.schema.json`: output of `mf version-sources --json`
+- `docs-review-list.schema.json`: output of `mf docs review list --json`
+- `explain-report.schema.json`: output of `mf explain authority --json`, `mf explain command --json`,  
+  `mf explain retention --json`, `mf explain skills --json`, and `mf explain surface --json`
+- `verify-report.schema.json`: output of `mf verify --reason <event> --json`
+- `change-verification-report.schema.json`: output of `mf verify --reason <event> --plan-only --json` and  
+  `mf verify --from-plan <path> --plan-only --json`
+
+These schemas define stable, automation-facing fields. Human-readable command  
+output is intentionally excluded.
+
+The published schema surface is tracked in `src/core/public-json-contracts.ts`.  
+Release tests verify consistency between this manifest, `schemas/*.schema.json`,  
+`npm pack --dry-run --json`, and the installed package’s JSON command output.