mustflow 2.112.4 → 2.112.8

package/templates/default/locales/en/.mustflow/skills/module-boundary-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.module-boundary-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: module-boundary-review
-description: Apply this skill when code is created, changed, reviewed, or reported and module separation, cohesion, coupling, data ownership, rule ownership, failure ownership, import direction, circular dependency, DTO leakage, shared/common/utils growth, mock-heavy tests, repeated policy conditions, enum interpretation, repository business logic, anemic domain, domain-to-I/O leakage, transaction boundary mismatch, event naming, public API bloat, caller sequencing, premature reuse, co-change history, bug/fix distance, config ownership, log responsibility, exception translation, cache invalidation ownership, repeated authorization checks, frontend/backend policy leakage, time policy, batch or worker bypass, or temporary-code accumulation can make a change spread beyond its real owner.
+description: Apply this skill when code is created, changed, reviewed, or reported and module separation, cohesion, coupling, change axes, stability direction, data ownership, rule ownership, failure ownership, import direction, circular dependency, DTO leakage, shared/common/utils growth, mock-heavy tests, repeated policy conditions, enum interpretation, repository business logic, anemic domain, domain-to-I/O leakage, transaction boundary mismatch, event naming, public API bloat, caller sequencing, premature reuse, co-change history, bug/fix distance, config ownership, log responsibility, exception translation, cache invalidation ownership, repeated authorization checks, frontend/backend policy leakage, time policy, batch or worker bypass, shallow modules, or temporary-code accumulation can make a change spread beyond its real owner.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -46,6 +46,12 @@ who must change, who owns the data, who owns the failure, and who should not nee
   files repeatedly change together.
 - A review claims that layering, clean architecture, DDD, modular monolith, feature folders,
   repositories, services, shared utilities, events, DTOs, or frontend/backend separation is clean.
+- A design starts from feature folders, technical layers, or CRUD nouns and may be missing the real
+  split criterion: who changes the code, when, why, and independently of which other owners.
+- A module depends on a more volatile detail such as a provider SDK, UI route flow, database query
+  shape, external response, framework object, config dialect, or generated transport model.
+- A change creates many thin files whose public APIs are wider than the hidden implementation, or
+  whose abstractions only forward calls, wrap switches, or rename CRUD.
 - The suspected issue is not a large service split yet, but a local module boundary that leaks
   business rules, data shape, failure handling, sequencing, or ownership to neighbors.
 
@@ -70,12 +76,21 @@ who must change, who owns the data, who owns the failure, and who should not nee
 
 - Change reason: the policy, feature, bug, data shape, failure path, or operational behavior that
   caused the edit.
+- Change-axis ledger: likely independent changes over the next useful planning horizon, including
+  policy, external provider, data model, UI flow, permission, pricing, billing, deployment, and
+  operational changes, plus who or what would cause each change.
 - Changed-file spread: folders, modules, layers, packages, tests, generated files, templates, and
   docs touched by the same reason.
 - Co-change evidence when available: recent commits, PRs, repeated paired files, or local diff
   history showing files that usually move together.
 - Module graph evidence: imports, exports, public APIs, call sites, dependency direction, cycles,
   shared helpers, DTO flow, and configuration reads.
+- Stability evidence: which modules many callers rely on, which modules change because external
+  details move, and whether dependencies point toward the more stable policy owner rather than the
+  more volatile implementation detail.
+- Change-simulation evidence: expected files touched for at least three concrete next changes, such
+  as changing a payment provider, adding a pricing rule, changing admin UI flow, changing invoice
+  format, changing permissions, or adding a worker path.
 - Configured guardrail evidence when available: `code/module-boundary` results for
   `.mustflow/config/module-boundaries.toml` layer deny rules, public entrypoints, feature imports,
   shared budgets, and import cycles.
@@ -121,15 +136,30 @@ who must change, who owns the data, who owns the failure, and who should not nee
    - Count how many modules, folders, layers, tests, docs, and templates changed for that one reason.
    - If one policy edit forces controller, service, repository, mapper, utility, constants, worker,
      and UI edits together, treat the module boundary as suspect.
+   - Before accepting a new split, list the independent change axes first. Do not start with
+     `controllers`, `services`, `repositories`, `utils`, or CRUD nouns unless the repository already
+     proves those are the real change units.
 2. Group by reason to change.
    - Files with different names but the same change reason are one module candidate.
    - `UserService`, `UserValidator`, `UserMapper`, `UserPolicy`, and `UserHelper` changing together is
      evidence of sliced roles, not necessarily separated modules.
+   - Write each candidate module as "this module changes when ...". If that sentence names more than
+     one independent owner, split the candidate or report the boundary risk.
+   - Prefer volatility names and business capabilities, such as pricing policy, payment provider,
+     subscription lifecycle, invoice rendering, fraud check, fulfillment handoff, or entitlement
+     decision, over role-sliced layer names when those better predict future edits.
 3. Check import direction.
    - Infrastructure or low-level modules should not know high-level business use case names unless
      the repository intentionally uses that inversion.
    - Treat lower layers importing policy names such as plan, checkout, approval, permission, or
      subscription as evidence that the policy leaked downward.
+   - Check stability direction. Code that many callers depend on should not import volatile details
+     such as Stripe, Toss, Prisma, SQLAlchemy, React Router, FastAPI request objects, provider DTOs,
+     raw SQL builders, generated clients, or `process.env` unless the repository explicitly makes
+     that layer an edge adapter.
+   - Prefer interfaces or ports owned by the using side when the abstraction protects stable policy
+     code from an unstable provider, database, queue, cache, filesystem, network, framework, or UI
+     detail.
 4. Treat cycles as boundary failure until proven harmless.
    - If A imports B and B imports A, identify the missing concept, ownership decision, event, port, or
      data-flow direction.
@@ -188,6 +218,11 @@ who must change, who owns the data, who owns the failure, and who should not nee
     - Too many exported functions can mean internals are on display.
     - If callers must call `create`, then `apply`, then `reserve`, then `mark`, the module has handed
       out an assembly manual instead of owning the sequence.
+    - A good module should have a small door and a deeper inside. If most files only expose one-line
+      forwarding methods, wrapper services, or renamed CRUD calls, treat the split as shallow module
+      theater until a real hidden decision or variation point is named.
+    - A public API wider than the behavior it hides is usually not a boundary; it is implementation
+      leakage with extra navigation.
 16. Check reuse claims.
     - "Used in many places" is not enough reason to extract a common helper.
     - Reuse is safe only when the callers change for the same reason. Similar code from different
@@ -197,20 +232,27 @@ who must change, who owns the data, who owns the failure, and who should not nee
       names.
     - If a file repeatedly receives temporary exceptions in the same direction, name the missing
       concept instead of adding another branch.
-18. Compare bug location with fix location.
+18. Run change simulations.
+    - Pick at least three plausible next changes from the change-axis ledger.
+    - For each scenario, list which modules should change and which modules must stay ignorant.
+    - If changing a provider, UI flow, invoice format, permission rule, or pricing rule repeatedly
+      crosses the same unrelated modules, treat that as hidden coupling.
+    - If a module would break because a different module's test changed, identify whether the
+      boundary couples futures that should be independent.
+19. Compare bug location with fix location.
     - If the symptom appears in one module but the fix belongs in an unrelated utility, policy, or
       mapper, the responsibility line may be bent.
-19. Check config, time, and logging responsibility.
+20. Check config, time, and logging responsibility.
     - Raw `process.env`, feature flag, remote config, clock, timezone, locale, and date parsing should
       usually be read at the edge and injected as explicit values.
     - Logs that mention another module's job, such as payment code logging welcome-email failure, are
       strong ownership evidence.
-20. Translate exceptions at boundaries.
+21. Translate exceptions at boundaries.
     - Database, provider, filesystem, framework, and payment errors should not leak through every
       layer unchanged.
     - Convert external failure dialect into the receiving module's language while preserving safe
       diagnostic causes.
-21. Check cache invalidation, authorization, frontend policy, and alternate entrypoints.
+22. Check cache invalidation, authorization, frontend policy, and alternate entrypoints.
     - Cache invalidation belongs near the data owner, not scattered across random callers.
     - Authorization checks repeated in controllers should move to one use-case entry, policy, or
       capability boundary.
@@ -218,7 +260,14 @@ who must change, who owns the data, who owns the failure, and who should not nee
       backend policy from internal statuses.
     - Batch, cron, worker, and admin tools should use the same use case or policy owner as online
       requests instead of bypassing validations, events, logs, and permissions.
-22. Decide the smallest response.
+23. Attack the design before accepting it.
+    - Name the three modules or abstractions most likely to rot first.
+    - For each, name the change request that would break it, the owner that would cause the change,
+      and whether the blast stays inside one module.
+    - Remove or redesign shallow wrappers, central managers, enum-switch strategies, provider-shaped
+      "neutral" ports, configuration-driven logic hiding, event-bus call hiding, and CRUD stamp
+      modules when they fail the attack.
+24. Decide the smallest response.
     - If evidence is strong and the edit is in scope, make the smallest boundary fix.
     - If the fix would be broad, report the module boundary risk and the first safe split point.
     - If evidence is weak, leave the structure alone and report the missing co-change or ownership
@@ -229,9 +278,15 @@ who must change, who owns the data, who owns the failure, and who should not nee
 
 - The changed reason, changed-file spread, co-change evidence, data owner, policy owner, failure
   owner, and public module surface are explicit or reported as missing.
+- The relevant change axes and stability direction are explicit, or reported as missing evidence.
+- At least three change simulations were checked when designing or accepting a new module boundary,
+  unless the task is only auditing an existing small local diff.
 - Import direction, cycles, DTO spread, shared helper ownership, repository policy leakage, domain
   I/O leakage, transaction mismatch, event naming, caller sequencing, duplicated policy, and alternate
   entrypoints are fixed or reported where relevant.
+- Shallow module signals such as role-sliced CRUD layers, one-line wrappers, provider-shaped ports,
+  ownerless managers, event-bus call hiding, config-hidden logic, and public API bloat are removed,
+  justified, or reported.
 - Any new abstraction hides a named responsibility and reduces caller knowledge, change spread, or
   test mock cost.
 - Behavior, public contracts, permissions, data ownership, and failure semantics remain intact or
@@ -276,11 +331,13 @@ design is clean.
 ## Output Format
 
 - Module boundary reviewed
-- Change reason and changed-file spread
+- Change reason, change axes, stability direction, and changed-file spread
 - Co-change, import direction, cycle, DTO, shared helper, public API, caller sequencing, and test mock
   evidence
 - Data owner, policy owner, failure owner, cache invalidation owner, config/time owner, and
   authorization owner where relevant
+- Change simulations and most-likely-to-rot modules
+- Shallow module signals found, fixed, justified, or deferred
 - Boundary fixes made or recommended
 - Evidence level: current diff, local source evidence, history evidence, configured-test evidence,
   missing, or not applicable

package/templates/default/locales/en/.mustflow/skills/readme-evidence-gate/SKILL.md

@@ -0,0 +1,183 @@
+---
+mustflow_doc: skill.readme-evidence-gate
+locale: en
+canonical: true
+revision: 4
+lifecycle: mustflow-owned
+authority: procedure
+name: readme-evidence-gate
+description: Apply this skill when README content is generated, reviewed, or audited for unsupported claims, README-as-investment-deck overclaim, unshipped roadmap-as-current wording, fake or internal-demo usage examples, subjective maintenance-debt wording such as TODO later, temporary, for now, probably, internal team reasons, ask Slack or a person, sample may differ, or see code, and drift-prone executable README contracts such as install, setup, run, dev server, test, build, Docker, environment, API, CLI output, package-manager guidance, support matrices, badges, roadmap, architecture, file-tree explanations, license, trademark, copyright, credit, attribution, or security-exposure surfaces such as real-looking fake keys, internal URLs, production paths, API keys in query strings, screenshots, and pasteable production commands.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.readme-evidence-gate
+  command_intents:
+    - docs_validate_fast
+    - test_related
+    - test_release
+    - mustflow_check
+---
+
+# README Evidence Gate
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent README prose from becoming a contract for features, setup paths, APIs, safety claims, or future work that the repository does not actually support.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- README text is generated from code, issue notes, AI output, review feedback, or a rough project summary.
+- A README draft lists features, quick-start steps, install or run commands, environment variables, public APIs, supported platforms, architecture, license, roadmap, security, performance, or scalability claims.
+- A README review needs to find hallucinated claims, fake commands, invented environment variables, unsupported examples, or marketing words that outrun the code.
+- A README uses production-ready, enterprise-grade, one-line integration, platform, system, engine, support, badge, or roadmap language that may describe aspiration instead of shipped behavior.
+- README examples may call desired APIs instead of current public APIs, hide internal demo prerequisites, or omit normal failure paths such as auth failure, timeout, empty data, permission denied, rate limit, pagination, or idempotency.
+- README, `.env.example`, examples, screenshots, or contribution templates may expose real-looking fake keys, API keys in URL query strings, internal domains, private IPs, admin URLs, production paths, bucket names, customer identifiers, or pasteable production commands.
+- A README contains TODO, later, temporary, for now, probably, usually, team-reason, legacy, not organized yet, ask Slack or person, production differs, sample may differ, or see code wording that describes a person's work state instead of the current user contract.
+- README code blocks, command examples, CLI output snippets, import examples, environment examples, install instructions, test commands, build output paths, server startup instructions, or runtime support statements need to be checked as pasteable contracts.
+- README license, trademark, copyright, attribution, credit, third-party asset, AI-generated content, or open-source status claims need to be checked against repository-owned rights and notice evidence.
+- `readme-authoring` is active and the README contains more than a small link-only or typo-only change.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only fixes spelling, broken anchors, or formatting and does not add or preserve factual claims.
+- The task edits a non-README documentation page whose owning skill has a stricter claim-evidence procedure.
+- The user explicitly asks for speculative marketing copy, a pitch, or roadmap ideation outside repository truth.
+- The repository evidence is unavailable and the task can be completed by reporting the missing evidence without editing the README.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The README draft or existing README sections under review.
+- Repository evidence for each factual claim: manifests, command contracts, package manager metadata, lockfiles, package scripts, `bin`, `exports`, `main`, `module`, `types`, source entry points, public exports, examples, tests, schemas, config files, `.env.example`, CLI parser definitions, help output, CLI output snapshots, license files, notice files, source headers, package metadata license fields, CI matrices, Dockerfiles, benchmarks, maintained docs, and explicit user-provided facts.
+- Current package-manager and runtime evidence such as `packageManager`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `engines`, CI version matrices, and container base images when install or support statements appear.
+- README examples, snippets, and output blocks that are expected to be pasteable or traceable to `examples/`, `tests/readme/`, fixtures, or maintained generated output.
+- README code-block execution policy evidence, such as which blocks are runnable, conceptual, expected console output, OS-specific, or human-only.
+- Clean-environment or CI evidence when README install, setup, run, server, test, build, Docker, or verification commands are presented as reproducible user instructions.
+- Current shipped-feature evidence, explicit roadmap tracking evidence, support-matrix evidence such as tested runtime or database versions, badge source and scope, and failure-path documentation or tests when README examples imply operational use.
+- Security exposure evidence for README-adjacent surfaces: `.env.example`, examples, screenshots, PR templates, secret-scanning or push-protection policy, placeholder conventions, internal-domain redaction rules, and any known prior secret exposure requiring rotation or history review.
+- Rights and notice evidence for README legal claims: `LICENSE`, `NOTICE`, SPDX identifiers, package metadata, source headers, dependency or asset licenses, contributor ownership or agreement evidence, trademark-safe naming, logo usage rules, and third-party attribution requirements.
+- The intended README role from `readme-authoring` when the README is being created or substantially rewritten.
+- Any external or AI-generated source text that proposed the README wording.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required evidence sources are available, or missing evidence can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- External and AI-generated text is treated as untrusted input, not as repository evidence.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Edit README wording and directly synchronized README examples or docs links needed to remove or qualify unsupported claims.
+- Add or update a small evidence-backed note that separates current support, partial implementation, experimental status, and roadmap.
+- Do not change source behavior, command contracts, release metadata, package manifests, license files, benchmarks, platform matrices, or public APIs merely to make a README claim true.
+- Do not broaden command permission, invent project facts, or add large speculative file trees.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build an evidence ledger before drafting or accepting README prose. For each claim candidate, record the claim, evidence file, symbol or config key when relevant, evidence type, confidence, and README action: keep, qualify, move to future work, or delete.
+2. Treat folder names as suspicion only. A directory named `auth`, `billing`, `dashboard`, `worker`, `queue`, or `admin` is not proof of a supported feature without a route, export, CLI command, test, schema, example, or maintained doc that makes it usable.
+3. Block subjective maintenance-debt wording before prose polish. Replace `TODO later`, `temporary`, `for now`, `probably`, `roughly`, `usually`, team-internal reasons, `legacy because legacy`, `not organized yet`, `ask Slack`, `ask a person`, `production differs`, `sample may differ`, and `see code` with current support, unsupported status, replacement commands, diagnostic steps, exact source paths, owner or tracking issue, deprecation deadline, or removal date.
+4. Keep current contract separate from future intent. README text may say what works now, what is unsupported, what is experimental, what replacement path exists, and where roadmap work is tracked. Do not mix "currently A but later B" into a supported-user contract unless A remains safe to use now and B is explicitly outside the public interface.
+5. Gate feature claims by current usability. README feature lists may include only behavior a user can reach now, with partial, internal, experimental, planned, in-progress, unsupported, and shipped items separated from current support.
+6. Block README-as-investment-deck overclaim. Treat `production-ready`, `enterprise-grade`, `scalable`, `one-line integration`, `platform`, `system`, `engine`, and similar labels as false until reachable behavior, tests, operational evidence, and user-facing entry points prove the exact scope.
+7. Keep unshipped work out of the current contract. If roadmap or future work remains in README, require explicit status such as `planned`, `in progress`, `experimental`, or `shipped`, plus tracking evidence, scope, owner or review path, and removal criteria. Otherwise move it out of the README.
+8. Gate API and usage examples against the real public surface. Examples must call current public APIs, CLI entry points, or maintained examples, not hoped-for methods or copied competitor README concepts such as plugin, adapter, middleware, or provider support that this repository does not expose.
+9. Surface hidden internal demo prerequisites. If an example depends on account rights, region, model access, proxy settings, sample databases, migrations, workers, Redis, Postgres, queues, admin tokens, or internal fixtures, state the prerequisite or remove the example from the general quick start.
+10. Define support as tested support. Replace broad support claims with tested ranges such as `tested with PostgreSQL 15 and 16` when evidence exists; do not treat "worked once locally" as supported platform, database, provider, browser, OS, or runtime coverage.
+11. Treat badges and numbers as scoped signals, not stability proof. Build badges, coverage, download counts, stars, benchmarks, and adoption numbers need a source, scope, and date when used; they cannot substitute for feature, readiness, security, or support evidence.
+12. Require failure-path evidence for operational examples. When README examples imply normal production use, point to or include behavior for auth failure, timeout, empty data, permission denied, rate limit, pagination, and idempotency when those conditions are relevant to the documented API or workflow.
+13. Keep experimental features visually and procedurally separate. Do not promote experimental features in the primary install flow, first quick start, main screenshot, or top feature list unless the README makes the experimental boundary impossible to miss.
+14. Gate package-manager and install guidance by declared sources. Match install commands to lockfiles and package metadata such as `packageManager`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, and `bun.lock`; do not default to npm, yarn, pnpm, Bun, Docker, or global CLI installation because it is common in the ecosystem.
+15. Prefer reproducible install wording when the repository evidence supports it. For example, lockfile-backed Node README instructions should favor `npm ci` over a mutating `npm install` path when npm lockfile evidence exists, and Python dependency instructions should include `python -m pip check` after requirements installation when that is part of the maintained setup contract.
+16. Gate commands by declared or maintained sources. Installation, quick-start, development, test, build, Docker, deployment, and verification commands must come from package scripts, command contracts, Makefiles, Docker or Compose files, language manifests, maintained docs, or explicit user instructions. Distinguish development server commands from production build and start commands.
+17. Statically map README commands to real entry points before prose polish. A package script reference such as `npm run dev` must exist in package metadata, a language-framework command such as `python manage.py runserver` must have the named entry file, a Compose service must exist in Compose config, and a container example must identify a real image or build path instead of nonsense placeholders such as `docker run .`.
+18. Separate install, setup, run, server-readiness, test, and build claims. Do not let one successful command imply the rest of the README workflow works. When the README presents server startup as runnable, require a readiness signal such as a health endpoint, expected port, expected page response, or documented manual boundary.
+19. Label README code blocks by execution status when the repository uses or adopts such a convention. Keep runnable shell blocks such as `bash verify` separate from expected console output, conceptual snippets, `bash no-run`, destructive or human-only commands, and OS-specific examples so automated extraction cannot run placeholder text.
+20. Check OS and shell boundaries for pasteable instructions. A README that claims Windows, macOS, Linux, Bash, cmd, or PowerShell support must not mix incompatible environment-variable syntax, path syntax, line continuations, or prompt markers without labeling the target shell.
+21. Gate CLI names and options by executable surfaces. README CLI names must match `bin` or documented entry points, and options, aliases, defaults, required flags, help text, output examples, stdout/stderr shape, and exit semantics must match CLI parser code, `--help`, fixtures, snapshots, or maintained output tests.
+22. Gate environment variables by code or config. Document only variables found in source lookups, config schemas, runtime manifests, `.env.example`, or maintained configuration docs. If README and `.env.example` disagree, fix the README only when the code evidence supports it, otherwise report the conflict.
+23. Gate API examples by public surface. Library examples must start from public exports, documented CLI entry points, generated API references, or tested examples. Match import paths against `exports`, `main`, `module`, `types`, source entry points, and declaration output. Do not document internal helpers, guessed import paths, guessed argument order, or sync/async behavior without source evidence.
+24. Treat README code blocks as pasteable contracts. Prefer examples under `examples/`, `tests/readme/`, fixtures, generated output snapshots, or CI-exercised README examples when feasible; otherwise qualify conceptual snippets so they cannot be mistaken for runnable setup, API, CLI, or deployment instructions.
+25. Gate README security exposure as if the README is public distribution, even for private repositories. README, `.env.example`, examples, screenshots, and package artifacts can leak through package publication, Docker images, wikis, customer handoffs, and LLM/code scans.
+26. Use placeholder-shaped secrets only. Do not include real credentials or real-looking fake keys such as `sk_live_...`, `AKIA...`, or `ghp_...`; use placeholders such as `replace-with-your-api-key` and avoid real domains, project IDs, regions, account names, bucket names, tenant IDs, or customer names.
+27. Keep secrets out of URLs and pasteable production commands. Ban API keys in URL query strings; prefer `Authorization` header examples. Do not include pasteable production commands such as production `kubectl`, destructive pod, real backup bucket, production migration, or production deploy commands in README.
+28. Redact internal and production topology. Replace internal URLs, private IPs, admin URLs, staging or production domains, production filesystem paths, deployment user paths, private-key paths, cluster names, database names, and bucket names with `example.com`, `example.test`, or `localhost` placeholders.
+29. Check screenshots and images as README content. Do not accept screenshots that show tokens, auth headers, account IDs, internal URLs, private IPs, dashboards, logs, incident IDs, customer names, tenant IDs, or production identifiers.
+30. Treat historical secret exposure as an incident, not a prose fix. If README, docs, examples, or screenshots ever contained a real secret, report the need for revocation, rotation, history scanning, and log review; deleting the current line is not sufficient.
+31. Gate test, build, and runtime support claims against real surfaces. Test commands must match the configured runner and script options; build output paths must match the configured build result; supported versions must match `engines`, CI matrices, runtime APIs, and Dockerfiles rather than hope or convention.
+32. Gate README legal claims as repository contracts, not slogans. Do not say `open source`, `MIT`, `Apache`, `GPL`, `commercial use allowed`, `no attribution required`, `official`, `certified`, `partner`, or similar rights/status language unless `LICENSE`, `NOTICE`, SPDX identifiers, package metadata, source headers, third-party notices, asset attributions, contributor rights, and trademark-safe wording agree.
+33. Use exact SPDX identifiers when a README names a software license. Keep `Apache-2.0`, `MIT`, `GPL-3.0-only`, `GPL-3.0-or-later`, and similar identifiers aligned across README, license files, package metadata, source headers, and notice surfaces.
+34. Preserve license conditions instead of collapsing them into permission slogans. If the README says commercial use is allowed, also preserve required notice, attribution, source-availability, copyleft, patent, NOTICE, or network-use obligations when they apply.
+35. Keep code, docs, assets, and trademarks separate. Creative Commons may fit docs, art, or media but is usually not the right software-code license; open-source code rights do not grant trademark or logo rights; and third-party asset credits should identify title, author, source, license, and modification status when the license requires it.
+36. Treat AI-generated provenance claims as weak evidence. A README cannot waive attribution, copyright, license, asset, snippet, or trademark obligations merely by saying content was AI-generated.
+37. Gate security, privacy, production-readiness, encryption, authorization, role-based access, secret handling, performance, scalability, benchmark, lightweight, platform-support, compatibility, and license claims with explicit evidence. Prefer deletion or narrow wording when evidence is missing.
+38. Gate architecture explanations by executable structure. Do not describe queues, workers, microservices, databases, caches, frontends, backends, deployment topology, or failure domains unless those surfaces exist in current code, config, infra files, tests, or maintained architecture docs.
+39. Keep file-tree explanations short and entry-point oriented. Include only paths a README reader needs to start, configure, verify, or contribute; do not describe broad folders from their names.
+40. Run a reverse audit after the draft: scan every README sentence for unsupported nouns, verbs, adjectives, numbers, commands, env vars, imports, platforms, code blocks, output snippets, screenshots, rights claims, internal-state wording, and future-tense promises. Remove or qualify anything missing ledger evidence.
+41. Treat high-risk adjectives as blocked until proven: `production-ready`, `secure`, `encrypted`, `scalable`, `enterprise-grade`, `robust`, `battle-tested`, `fully featured`, `seamless`, `10x`, `lightweight`, and similar marketing claims.
+42. Activate narrower skills before accepting claims that belong to another contract surface:
+   - command examples, help text, JSON output, or exit semantics: `command-intent-mapping-gate`, `cli-option-contract-review`, or `cli-output-contract-review`;
+   - external tool versions, provider behavior, package-manager guidance, or current compatibility: `source-freshness-check` or `version-freshness-check`;
+   - security, privacy, secrets, permission, retention, or disclosure claims: `security-privacy-review`;
+   - license, provenance, copied content, or third-party asset claims: `provenance-license-gate`;
+   - package contents, release readiness, install behavior, or template output: `release-publish-change` or `template-install-surface-sync`.
+43. When README changes are reviewed through pull requests or release gates, prefer reproducibility evidence over prose approval. Installation logs, server readiness logs, test logs, build logs, or packaged README example artifacts should back the claim when configured checks exist; otherwise report the missing evidence instead of treating a sentence review as proof.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Each README factual claim is backed by repository evidence, explicitly qualified, or removed.
+- Subjective TODO, temporary, internal-reason, ask-person, sample-may-differ, and see-code wording is removed or converted into current support, unsupported status, replacement path, diagnostic step, exact source path, owner or tracking evidence, deadline, or tracking issue.
+- Current support, partial implementation, experimental work, and roadmap are not mixed.
+- Unshipped roadmap items, internal demo prerequisites, fake desired APIs, overbroad support claims, unsupported badges, copied competitor concepts, and experimental promotion are separated, qualified, removed, or reported.
+- Unsupported commands, environment variables, API examples, security, performance, platform, license, trademark, copyright, attribution, architecture, and file-tree claims are absent or reported.
+- README security exposure is removed or reported: real-looking fake keys, URL-query secrets, internal URLs, private IPs, production paths, pasteable production commands, sensitive identifiers, unsafe screenshots, and missing secret rotation or history-scan follow-up after known exposure.
+- README code blocks, command examples, CLI output snippets, import examples, environment examples, test commands, build output paths, server readiness claims, OS-specific shell examples, and runtime support statements are pasteable, tested, explicitly conceptual, or reported as unverified.
+- README legal and credit claims agree with license, notice, SPDX, package metadata, source-header, dependency, asset, contributor, and trademark evidence, or are removed or reported.
+- Any evidence gap, conflict, or deferred verification is named in the final report.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `docs_validate_fast`
+- `mustflow_check`
+
+Use `test_related` when README examples, command snippets, public API usage, or generated examples are changed and the configured related tests cover them.
+Use `test_release` when package installation, package contents, release metadata, template install output, or README examples in packaged artifacts are affected.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a README claim lacks evidence, remove it or qualify it instead of searching for weaker hints.
+- If evidence conflicts across code, tests, docs, and manifests, keep the README conservative and report the conflict.
+- If the user asks to keep a claim that cannot be proven, mark it as unverified or future work only when that wording is honest.
+- If verification fails, fix the first README-related broken link, stale command, unsupported example, or template drift before adding new prose.
+- If this gate would require changing code to match README prose, stop and report that the README claim outruns the implementation.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- README sections gated
+- Evidence ledger summary
+- Claims kept, qualified, moved, or removed
+- Subjective maintenance-debt phrases removed or converted
+- README overclaim, roadmap, support, badge, fake-example, internal-demo, experimental, and failure-path checks performed
+- Pasteable README contract checks performed
+- README security exposure checks performed
+- README executable-command, clean-environment, code-block-label, OS-shell, server-readiness, and env-key consistency checks performed
+- README license, SPDX, NOTICE, trademark, contributor-rights, third-party credit, and AI-provenance checks performed
+- Unsupported commands, environment variables, APIs, security, performance, platform, license, roadmap, architecture, or file-tree claims found
+- Related skills activated or deferred
+- Command intents run
+- Skipped command intents and reasons
+- Remaining README evidence risk

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

@@ -198,6 +198,12 @@ route_type = "adjunct"
 priority = 76
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
 
+[routes."abstraction-boundary-review"]
+category = "general_code"
+route_type = "adjunct"
+priority = 77
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "data_change"]
+
 [routes."module-boundary-review"]
 category = "general_code"
 route_type = "adjunct"
@@ -1194,6 +1200,12 @@ route_type = "primary"
 priority = 50
 applies_to_reasons = ["docs_change"]
 
+[routes."readme-evidence-gate"]
+category = "docs_release"
+route_type = "adjunct"
+priority = 72
+applies_to_reasons = ["docs_change", "copy_change", "public_api_change", "package_metadata_change", "security_change", "performance_change", "release_risk", "unknown_change"]
+
 [routes."release-notes-authoring"]
 category = "docs_release"
 route_type = "primary"

package/templates/default/locales/en/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 19
+revision: 20
 lifecycle: user-editable
 authority: binding
 ---
@@ -115,6 +115,10 @@ mustflow-managed details are under `.mustflow/`.
   Follow the stricter rule.
 - When navigating to a nested repository, reread that repository's `AGENTS.md` and
   `.mustflow/config/*.toml` before editing.
+- In repository farms, prefer each child repository's own command contract for repository-owned
+  commands. If the parent root intentionally orchestrates children, split parent-owned commands
+  into repo-named fragments under `.mustflow/config/commands/`; use
+  `mf workspace command-fragments` for read-only guidance.
 - Do not edit outside the selected child repository unless explicitly requested.
 
 ## Host-Specific Instruction Compatibility

package/templates/default/locales/ko/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: ko
 canonical: false
-revision: 26
+revision: 27
 lifecycle: user-editable
 authority: binding
 ---
@@ -72,6 +72,7 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 - 작업 방식, 코드 스타일, 테스트 방식, 명령 실행 규칙이 충돌할 경우 하위 저장소의 `AGENTS.md`와 `.mustflow/config/commands.toml`을 우선합니다.  
 - 보안, 비밀 정보, 개인정보, 파괴적 명령, 수정 가능 경로 등 안전 규칙은 누적 적용하며 더 엄격한 규칙을 따릅니다.  
 - 상위 작업 공간에서 하위 저장소로 진입한 경우, 하위 저장소의 `AGENTS.md`와 `.mustflow/config/*.toml`을 다시 읽은 뒤 작업합니다.  
+- repository farm에서는 각 하위 저장소가 소유한 명령은 해당 저장소의 command contract를 우선합니다. 상위 루트가 하위 저장소를 의도적으로 orchestration해야 한다면 상위 소유 명령을 `.mustflow/config/commands/` 아래 repo 이름별 fragment로 나누고, `mf workspace command-fragments`로 읽기 전용 안내를 확인합니다.  
 - 명시적 요청 없이 선택한 하위 저장소 밖의 파일은 수정하지 않습니다.
 
 ## 호스트별 지침 호환성

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.112.4"
+version = "2.112.8"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -27,6 +27,7 @@ creates = [
   ".mustflow/skills/code-review/SKILL.md",
   ".mustflow/skills/ai-generated-code-hardening/SKILL.md",
   ".mustflow/skills/quality-gaming-guard/SKILL.md",
+  ".mustflow/skills/abstraction-boundary-review/SKILL.md",
   ".mustflow/skills/module-boundary-review/SKILL.md",
   ".mustflow/skills/change-blast-radius-review/SKILL.md",
   ".mustflow/skills/business-rule-leakage-review/SKILL.md",
@@ -198,6 +199,7 @@ creates = [
   ".mustflow/skills/cross-agent-session-reference/SKILL.md",
   ".mustflow/skills/structure-discovery-gate/SKILL.md",
   ".mustflow/skills/readme-authoring/SKILL.md",
+  ".mustflow/skills/readme-evidence-gate/SKILL.md",
   ".mustflow/skills/requirement-regression-guard/SKILL.md",
   ".mustflow/skills/repro-first-debug/SKILL.md",
   ".mustflow/skills/source-anchor-authoring/SKILL.md",
@@ -234,6 +236,7 @@ after_install = [
   "Read AGENTS.md for repository-specific working rules.",
   "Run mf doctor to inspect the current state before editing.",
   "Generate REPO_MAP.md with mf map when a repository map is needed.",
+  "For repo farms under projects/, run mf workspace command-fragments --projects-dir projects --json before putting many child-repository commands in one parent command file.",
   "Review the default Bun-backed test intents in .mustflow/config/commands.toml and replace them with narrower project commands when useful.",
   "Add your lint and build commands to .mustflow/config/commands.toml.",
   "Review repository-specific language and style defaults in .mustflow/config/preferences.toml.",
@@ -261,6 +264,7 @@ minimal = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -430,6 +434,7 @@ patterns = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -610,6 +615,7 @@ oss = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -766,6 +772,7 @@ oss = [
   "pure-core-imperative-shell",
   "proactive-risk-surfacing",
   "readme-authoring",
+  "readme-evidence-gate",
   "release-notes-authoring",
   "release-publish-change",
   "repo-improvement-loop",
@@ -808,6 +815,7 @@ team = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -991,6 +999,7 @@ product = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -1180,6 +1189,7 @@ library = [
   "code-review",
   "ai-generated-code-hardening",
   "quality-gaming-guard",
+  "abstraction-boundary-review",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -1335,6 +1345,7 @@ library = [
   "pure-core-imperative-shell",
   "proactive-risk-surfacing",
   "readme-authoring",
+  "readme-evidence-gate",
   "release-notes-authoring",
   "release-publish-change",
   "result-option",