mustflow 2.31.0 → 2.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -185,6 +185,12 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.heuristic-candidate-selection"]
+source = "locales/en/.mustflow/skills/heuristic-candidate-selection/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.astro-code-change"]
 source = "locales/en/.mustflow/skills/astro-code-change/SKILL.md"
 source_locale = "en"
@@ -559,13 +565,13 @@ translations = {}
 [documents."skill.security-privacy-review"]
 source = "locales/en/.mustflow/skills/security-privacy-review/SKILL.md"
 source_locale = "en"
-revision = 21
+revision = 22
 translations = {}
 
 [documents."skill.security-regression-tests"]
 source = "locales/en/.mustflow/skills/security-regression-tests/SKILL.md"
 source_locale = "en"
-revision = 11
+revision = 12
 translations = {}
 
 [documents."skill.search-ad-content-authoring"]

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -121,6 +121,7 @@ routes. Event routes stay inactive until their event occurs.
 | --- | --- | --- | --- | --- | --- | --- |
 | Code changes need review before report | `.mustflow/skills/code-review/SKILL.md` | Diff and task goal | Changed files | behavior and regression | `test`, `test_related`, `test_audit`, `lint` | Findings or no-issue note |
 | An unfamiliar codebase area needs an evidence-based map before planning, implementation, or reporting | `.mustflow/skills/codebase-orientation/SKILL.md` | User request, target area, relevant instructions, and current source, test, schema, template, configuration, or documentation files | Read-only orientation notes and any smallest follow-up edit chosen from inspected evidence | stale documentation, wrong ownership boundary, or invented architecture claim | `changes_status`, `changes_diff_summary`, `mustflow_check` | Scope inspected, entrypoints, flow map, ownership boundaries, verification options, risks, unknowns, and smallest safe next step |
+| Large-scope code, docs, tests, content, log, data, or refactor work needs cheap-signal candidate selection before reading or editing many files | `.mustflow/skills/heuristic-candidate-selection/SKILL.md` | User goal, target scope, file-role boundaries, cheap signals, exclusions, scoring factors, batch limit, and verification contract | Candidate discovery, scoring, read plan, bounded batch edits, and directly synchronized surfaces | token waste, false positives, generated-file noise, unimportant cleanup, hallucinated source content, oversized diff, or missed high-impact file | `changes_status`, `changes_diff_summary`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Selection goal, excluded surfaces, cheap signals, scored candidates, selected batch, skipped/deferred files, verification, and remaining selection risk |
 | A coding task has missing intent, scope, domain, data, security, UX, dependency, architecture, or verification decisions that cannot be safely inferred from repository evidence | `.mustflow/skills/clarifying-question-gate/SKILL.md` | User request, inspected repository evidence, unresolved decisions, reversibility classification, recommended option, and tradeoffs | Blocking questions, safe assumptions, and the smallest safe implementation boundary | over-questioning, lazy questions, expensive wrong assumptions, user-owned decision drift, data loss, auth bypass, public-contract drift, dependency bloat, or unverifiable completion | `changes_status`, `changes_diff_summary`, `mustflow_check` | Repository evidence inspected, blocking questions with recommendations, safe assumptions, selected scope, verification, and remaining ambiguity |
 | A task chooses, migrates, rewrites, or justifies a primary language, runtime, framework, compile target, or execution environment | `.mustflow/skills/runtime-target-selection/SKILL.md` | Current runtime surfaces, target options, product or system need, environment constraints, migration boundary, smoke targets, and performance or reliability claims | Decision records, skill procedures, route metadata, migration plans, command-contract proposals, tests, fixtures, docs, and smallest selected migration scaffold | language-preference rewrite, unsupported runtime target, unusable build loop, cache or artifact blowup, missing smoke target, deployment drift, or false performance claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_related`, `test_release`, `mustflow_check` | Decision boundary, candidate targets, environment and build-loop evidence, smoke targets, migration boundary, calibrated claims, verification, and remaining runtime-target risk |
 | Non-trivial code work needs early structure decisions around domain rules, public contracts, external I/O, operational safety, failure handling, concurrency, data flow, or future change cost | `.mustflow/skills/structure-first-engineering/SKILL.md` | User request, target files, project context, core boundary, data flow, expected failures, public contracts, I/O surfaces, and verification contract | Risk block, focused boundaries, DTOs, adapters, pure functions, error models, tests, and directly synchronized docs or contracts | under-designed hard boundary, speculative abstraction, vague service layer, mixed I/O and domain rules, hidden partial failure, or untestable behavior | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Work risk, structure decision, data flow, failure model, I/O and concurrency boundaries, tests, verification, and remaining structure risk |

package/templates/default/locales/en/.mustflow/skills/heuristic-candidate-selection/SKILL.md

@@ -0,0 +1,165 @@
+---
+mustflow_doc: skill.heuristic-candidate-selection
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: heuristic-candidate-selection
+description: Apply this skill when a large folder, repository, documentation set, or refactor request needs cheap-signal candidate selection before reading or editing many files.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.heuristic-candidate-selection
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Heuristic Candidate Selection
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from opening every file in a large scope before they know which files are likely to matter.
+
+Use cheap repository signals to rank candidate files, calibrate the ranking with small samples, read only the selected batch, and verify that the selected change actually improved the targeted risk.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The user asks to find sparse, stale, incomplete, weak, outdated, duplicate, oversized, risky, or refactor-worthy files across a broad folder or repository.
+- A request such as "fill in thin docs", "improve weak documents", "refactor files with too much code", "clean up this folder", "audit this area", or "find what to fix first" would otherwise tempt the agent to read many files.
+- The task needs candidate discovery before implementation, especially for documentation sets, content collections, tests, frontend components, backend services, logs, data files, migrations, or monorepo packages.
+- The next safe edit depends on separating file discovery, target selection, precise reading, and modification.
+- The user values efficient navigation, bounded context, or batch-by-batch work over a broad manual sweep.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task names one or two exact files and the required edit is already clear.
+- A failing command, stack trace, or reproduction path already identifies the first files to inspect; use `repro-first-debug` or `failure-triage`.
+- The task is only to orient in an unfamiliar area without ranking candidates; use `codebase-orientation`.
+- The task is only to choose a local precedent after the target file is known; use `pattern-scout`.
+- The user explicitly asks for exhaustive manual review of every file and accepts the cost.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, target scope, and whether the output should be analysis-only, candidate list, or implementation batch.
+- File-type and role boundaries, such as source, tests, docs, schemas, configs, generated files, assets, logs, data, migrations, or package surfaces.
+- Cheap signals available without reading every full file: file names, sizes, line counts, symbol or heading outlines, changed-file summaries, recent churn, inbound or outbound dependency hints, search hits, TODO-like markers, entrypoints, schema or config centrality, test proximity, user-facing routes, and generated-file markers.
+- Exclusion rules for generated output, vendored code, lockfiles, snapshots, build artifacts, caches, and intentionally tiny adapter, index, barrel, or marker files.
+- Risk and importance factors for the domain, such as user-visible route, public API, schema ownership, money, permission, data mutation, external I/O, runtime configuration, search exposure, internal-link centrality, or recent work-in-progress.
+- Batch limit, folder quota, confidence threshold, and verification intents relevant to the selected surface.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Candidate selection is needed before reading complete files.
+- Missing cheap-signal sources can be reported without inventing a ranking.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Analysis-only mode may produce a ranked candidate list, read plan, batch plan, and excluded-surface notes without changing files.
+- Implementation mode may edit only the selected bounded batch and directly synchronized files required by the chosen change.
+- Add or update lightweight audit helpers, fixtures, or docs only when the repository already has an appropriate owned surface or the user asked for reusable automation.
+- Do not read, summarize, or modify a whole large folder just because it is in scope.
+- Do not modify generated files, external dependencies, lockfiles, snapshots, or broad shared utilities unless the selected task explicitly requires that surface and the matching skill allows it.
+- Do not fill unknown source material, book summaries, external facts, API behavior, or domain claims from model memory. Mark such targets as `needs_source`, `needs_runtime_check`, or `needs_domain_decision`.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Define the selection job.
+   - Restate the user goal, target scope, intended deliverable, batch size, and whether edits are allowed now.
+   - Decide whether candidates should optimize for risk, importance, certainty, repair value, or low-cost cleanup.
+2. Classify file roles before scoring.
+   - Separate human-authored source from generated output, dependency folders, build artifacts, caches, snapshots, lockfiles, vendored code, and intentionally small glue files.
+   - Treat config, schema, route, permission, payment, data mutation, migration, queue, webhook, cache, and external-adapter files as high-impact even when small.
+3. Gather cheap signals before opening full files.
+   - Prefer file metadata, changed-file summaries, search hits, symbol or heading outlines, import or dependency hints, route maps, schema names, test names, warning summaries, and bounded head or tail previews.
+   - Use configured command receipts and declared generated maps only as evidence or navigation aids; they do not replace current files or command contracts.
+   - For documentation and content, score body-like content separately from frontmatter, imports, exports, component wrappers, links, images, quotes, code blocks, placeholders, and duplicated descriptions.
+   - For code, score churn, entrypoint proximity, dependency centrality, missing nearby tests, TODO-like markers, type bypasses, exception density, mutation paths, async or concurrency hints, config and schema ownership, and public-contract exposure.
+4. Build a candidate score instead of using one metric.
+   - Combine risk, importance, certainty, and estimated fix cost.
+   - Calibrate small-file findings by file role so index files, barrel exports, type declarations, marker files, and config shims are not treated as broken merely because they are short.
+   - For large-file refactors, prefer symbol outlines, export lists, responsibility clusters, churn, dependency centrality, and test coverage gaps before reading the whole file.
+   - For documentation gaps, compare each file to its sibling folder pattern and expected document role before calling it thin.
+5. Avoid tunnel vision.
+   - Limit candidates per folder or package so one noisy directory does not consume the whole batch.
+   - Include a small random or representative sample from lower-scored files to expose blind spots in the scoring formula.
+   - Select good sibling examples as references before editing weak files.
+6. Choose the read batch.
+   - Produce a ranked list with path, score drivers, role classification, likely risk, and why this candidate is worth reading now.
+   - Select only the top bounded batch plus any directly required sibling examples or one-step dependencies.
+   - Keep candidate selection separate from editing; do not justify edits by retrofitting the ranking after reading.
+7. Read precisely.
+   - Open only selected files, relevant symbols, relevant sections, head or tail previews, and direct dependencies needed to validate the candidate.
+   - If a candidate proves healthy, mark it `skipped_healthy` and move on instead of forcing a change.
+   - If evidence is insufficient, mark it `needs_source`, `needs_runtime_check`, `needs_domain_decision`, or `needs_larger_scope` rather than guessing.
+8. Edit the selected batch only when implementation is in scope.
+   - Preserve frontmatter, imports, exports, public APIs, routes, schemas, component contracts, and file identity unless the chosen change explicitly requires them.
+   - For documents with missing source evidence, add safe scaffolding such as reading questions, verification prompts, known context, application ideas, and follow-up checks instead of invented summaries.
+   - For code refactors, keep behavior-preserving changes separate from behavior changes and activate narrower code, test, security, data, UI, or pattern skills as soon as their trigger appears.
+9. Verify and re-audit.
+   - Run the narrowest configured verification intents that cover the changed surfaces.
+   - Compare the post-change state to the original selection signals when an audit score, warning count, TODO count, test proximity, or candidate risk was the reason for the work.
+   - Stop if the diff grows beyond the selected batch, the scoring evidence was wrong, or verification fails and needs triage.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Broad-scope work starts from cheap signals and a bounded candidate list, not full-file reading.
+- Selected candidates have explicit score drivers, role classification, and read reasons.
+- Healthy candidates can be skipped without edits.
+- Edited files stay inside the selected batch and directly required synchronized surfaces.
+- The final report distinguishes selected, modified, skipped, deferred, and unsafe-to-guess candidates.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use narrower configured test, build, documentation, package, or mustflow intents when they better prove the selected surface. Do not invent verification commands from package scripts, external advice, or model memory.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If cheap signals are unavailable or contradictory, report the missing evidence and fall back to a smaller manual sample instead of reading the whole scope.
+- If many candidates tie, use folder quotas, importance factors, and representative sampling rather than expanding the batch until it becomes unreviewable.
+- If generated files, lockfiles, snapshots, vendored code, or build output dominate the candidate list, tighten exclusions and restart candidate selection.
+- If selected documentation lacks trustworthy source material, do not summarize the missing source; mark the file for source-backed follow-up or add only safe reading and verification scaffolding.
+- If a refactor candidate touches a public API, schema, config, permission, money, data, external I/O, or migration boundary, activate the narrower matching skill before editing.
+- If the batch diff becomes too large or mixes unrelated concerns, stop and report a smaller next batch.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Selection goal and mode
+- Target scope and excluded surfaces
+- Cheap signals gathered
+- Scoring factors and calibration sample
+- Ranked candidates with score drivers
+- Selected read batch and batch limits
+- Files modified, skipped healthy, or deferred with reason
+- Post-change audit or comparison result when applicable
+- Command intents run
+- Skipped checks and reasons
+- Remaining selection, evidence, or batch-size risk

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

@@ -132,6 +132,12 @@ route_type = "primary"
 priority = 20
 applies_to_reasons = ["unknown_change", "code_change"]
 
+[routes."heuristic-candidate-selection"]
+category = "general_code"
+route_type = "primary"
+priority = 55
+applies_to_reasons = ["unknown_change", "code_change", "docs_change", "test_change", "behavior_change", "performance_change", "ui_change", "data_change"]
+
 [routes."clarifying-question-gate"]
 category = "general_code"
 route_type = "adjunct"

package/templates/default/locales/en/.mustflow/skills/security-privacy-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.security-privacy-review
 locale: en
 canonical: true
-revision: 21
+revision: 22
 lifecycle: mustflow-owned
 authority: procedure
 name: security-privacy-review
@@ -167,6 +167,8 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
    - Store processed event identifiers to avoid duplicate effects. Keep provider event payloads, request bodies, and response bodies out of ordinary logs and dead-letter records unless they are redacted and have a retention rule.
 22. For database-as-a-service, storage bucket, or realtime rules, check that server-side policies are default-deny, ownership-scoped, and not left in public read/write development mode.
 23. For input sinks, check parameterized queries, ORM binding, static command maps, output encoding, HTML/Markdown rendering boundaries, unsafe dynamic evaluation, XML/YAML/Markdown parser options, redirect and sort parameters, page-size limits, and framework escape hatches.
+   - For escaping, quoting, encoding, or sanitization alerts, identify the exact output domain first: URL component, URL path segment, HTML, SQL, shell argument, regular expression, Markdown, JSON, XML, YAML, log line, or filename. Prefer a structured, domain-aware encoder, parser, query binder, or URL API over manual string replacement.
+   - If custom escaping is unavoidable, prove that repeated metacharacters, backslashes, separators, quotes, existing encoded sequences, and reserved characters are handled according to that domain. Treat single-occurrence string replacement, non-global regular expressions, partial slash or quote handling, and `encodeURI` versus `encodeURIComponent` confusion as scanner-worthy patterns until reviewed.
 24. For file upload and download, check MIME and content signatures, size limits, storage outside executable web roots, SVG/HTML/PDF rendering rules, image or document metadata, filename controls, Unicode confusion, path traversal, download authorization, and resource limits for resizing, archive extraction, or document conversion.
    - Prefer server-generated asset ids or hash-like storage keys over user filenames in storage paths. Keep original filenames as metadata only.
    - For private files, avoid returning permanent public URLs or raw storage keys. Recheck authorization before issuing a short-lived signed download URL.
@@ -190,6 +192,7 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 31. For agent configuration, MCP/tool setup, prompt files, external instructions, or AI context settings, activate `external-prompt-injection-defense` and check hidden instruction text, suspicious Unicode controls, broad filesystem or shell permissions, network egress, sensitive context inclusion, and over-privileged service tokens.
 32. For filesystem changes, distinguish lexical containment from the real target. Check symlinks, generated state, package contents, and file APIs that may follow links before claiming a path stays inside the repository.
 33. For code-scanning alerts, group findings by root cause and rule. Fix the underlying pattern, not only the exact flagged line, and separate repository-setting alerts such as branch protection or maintainer activity from code changes.
+    - For incomplete escaping or encoding findings, search the same sink class for adjacent ad hoc sanitizer patterns such as first-occurrence `.replace`, non-global replacement, hand-escaped slashes, quotes, backslashes, path separators, or mixed URL encoders. Replace the pattern with a domain-owned transformation and add a regression test or narrow source-pattern guard when the behavior is release-sensitive.
 34. For workflow scanner alerts, check action pinning, `persist-credentials`, job-level permissions, reusable workflow permissions, fork pull-request secret exposure, artifact upload boundaries, and privileged identity timing before treating the warning as cosmetic.
 35. For pinned action references, distinguish tag objects from the commit that implements the tag. Verify pinned SHAs against the action repository so scanner tooling does not report an imposter or non-member commit.
 36. For dependency scanner alerts, separate production dependency manifests from fixtures, examples, generated test repositories, and intentionally vulnerable samples. Narrow the scan scope before treating fixture-only alerts as product vulnerabilities.

package/templates/default/locales/en/.mustflow/skills/security-regression-tests/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.security-regression-tests
 locale: en
 canonical: true
-revision: 11
+revision: 12
 lifecycle: mustflow-owned
 authority: procedure
 name: security-regression-tests
@@ -63,6 +63,7 @@ Convert security-sensitive behavior changes into safe negative tests that preser
 - Any project context or public contract that defines privacy, authorization, upload, callback, payment, or tenant rules.
 - The executable, shell, filesystem, package, or workflow boundary that should reject repository-controlled input.
 - Static-analysis rule identifier, flagged location, source-to-sink path, and the intended defensive outcome after the fix.
+- Escaping or encoding domain, dangerous metacharacters, repeated occurrences, existing encoded or reserved characters, and expected canonical output when the finding involves sanitization.
 - Existing fuzzing or property-based testing libraries, package metadata, lockfiles, and test-runner conventions when generated-input tests are added.
 
 <!-- mustflow-section: preconditions -->
@@ -111,7 +112,9 @@ Convert security-sensitive behavior changes into safe negative tests that preser
    - untrusted metadata override where a repository-controlled field, nested duplicate, component, owner, stage, tier, role, or exemption value is treated as trusted ownership or authorization evidence
    - invalid-but-present security control values where `false`, `0`, `{}`, `[]`, empty strings, or type-mismatched placeholders satisfy required policy fields
    - release or package-publishing pipeline code execution before artifact publication
-   - incomplete escaping, quoting, encoding, or sanitization where the safe behavior can be asserted without invoking a real shell or network target
+   - incomplete escaping, quoting, encoding, sanitization, or single-occurrence string replacement where the safe behavior can be asserted without invoking a real shell or network target
+     - Include repeated metacharacters, mixed safe and unsafe characters, leading or trailing separators, and domain-specific reserved characters in the smallest representative cases.
+     - Prefer asserting the canonical output or denied side effect from the project-owned encoder, URL builder, query binder, or renderer. Use source-pattern guards only when the runtime behavior is difficult to isolate, and do not assert scanner wording, line number, or severity.
    - stack trace or internal error exposure through a user-visible API, report, dashboard, or command output
    - insecure password storage, custom cryptography, weak hash use, insecure randomness, or predictable reset or invite tokens
    - disabled certificate validation, insecure HTTP downgrade, or missing HTTPS enforcement for sensitive traffic

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.31.0"
+version = "2.32.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -19,6 +19,7 @@ creates = [
   ".mustflow/skills/behavior-preserving-refactor/SKILL.md",
   ".mustflow/skills/code-review/SKILL.md",
   ".mustflow/skills/codebase-orientation/SKILL.md",
+  ".mustflow/skills/heuristic-candidate-selection/SKILL.md",
   ".mustflow/skills/clarifying-question-gate/SKILL.md",
   ".mustflow/skills/completion-evidence-gate/SKILL.md",
   ".mustflow/skills/evidence-stall-breaker/SKILL.md",
@@ -144,6 +145,7 @@ minimal = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",
@@ -210,6 +212,7 @@ patterns = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",
@@ -287,6 +290,7 @@ oss = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",
@@ -379,6 +383,7 @@ team = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",
@@ -457,6 +462,7 @@ product = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",
@@ -540,6 +546,7 @@ library = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "heuristic-candidate-selection",
   "clarifying-question-gate",
   "completion-evidence-gate",
   "evidence-stall-breaker",