mustflow 2.23.0 → 2.25.0

package/templates/default/locales/en/.mustflow/skills/clarifying-question-gate/SKILL.md

@@ -0,0 +1,183 @@
+---
+mustflow_doc: skill.clarifying-question-gate
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: clarifying-question-gate
+description: Apply this skill when a coding task has missing intent, scope, domain, data, security, UX, dependency, architecture, or verification decisions that cannot be safely inferred from current repository evidence.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.clarifying-question-gate
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - mustflow_check
+---
+
+# Clarifying Question Gate
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Ask only the questions that protect the work from expensive wrong assumptions.
+
+Good agent work is not maximally autonomous and not maximally interrogative. It moves forward on
+cheap, reversible, repository-evident decisions, and stops before choices that are costly to undo or
+whose correct answer belongs to the user, product owner, security owner, or operations owner.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The user asks for implementation, debugging, refactoring, UI, data, API, release, or workflow work
+  but the success criteria are not observable from the request or repository evidence.
+- The task may affect existing users, existing data, migrations, deletion, retention, auth,
+  authorization, billing, entitlements, files, secrets, external APIs, public CLI/API output,
+  user-visible UX policy, package dependencies, architecture, performance tradeoffs, or verification
+  expectations.
+- The task uses ambiguous domain words such as user, account, team, workspace, project, active,
+  complete, canceled, subscription, admin, owner, archived, deleted, invite, or verified.
+- Several implementation scopes are plausible and differ in cost, compatibility, risk, or future
+  maintenance burden.
+- You are about to add a new dependency, service, folder boundary, storage model, framework pattern,
+  persistent state, or broad refactor that the current files do not already require.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The answer is available by reading current files, tests, docs, config, or local patterns.
+- The change is small, local, reversible, and covered by an existing pattern or focused test.
+- The task is analysis-only and does not need an implementation decision.
+- A more specific skill already requires a blocking question for the same risk and covers the whole
+  decision, such as `structure-discovery-gate`, `auth-permission-change`, `database-migration-change`,
+  `dependency-upgrade-review`, or `release-publish-change`.
+- Asking would only delegate ordinary engineering responsibility, such as "should I add tests?",
+  "should I handle errors?", "what stack is this?", or "what style should I use?" when the repository
+  already answers it.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User request and any stated success criteria, constraints, examples, deadlines, or non-goals.
+- Relevant repository evidence: current files, tests, schemas, command contracts, docs, context,
+  nearby code patterns, and existing verification options.
+- Candidate decisions that are still ambiguous after reading local evidence.
+- Reversibility classification for each decision: cheap/reversible, moderate, or expensive/hard to
+  roll back.
+- A recommended option for each blocking question, with the tradeoff of at least one alternative.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Repository evidence has been inspected before asking. Do not ask the user to answer facts that the
+  codebase can answer.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current
+  scope.
+- Questions are limited to decisions that block safe implementation, not curiosity, preference
+  collection, or broad product discovery.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- No edits are required when the skill only gates a blocking decision.
+- When proceeding under a safe assumption, keep the implementation small enough that a wrong
+  assumption can be corrected locally.
+- Do not add dependencies, migrations, persistent data changes, permission policy, deletion behavior,
+  public contract changes, or broad refactors while a blocking question remains unanswered.
+- Do not create speculative specs, roadmaps, or documentation unless the user requested that artifact
+  or another selected skill authorizes that scope.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read enough local evidence to avoid lazy questions:
+   - current feature code, nearby tests, schemas, docs, command contracts, and context files when
+     relevant;
+   - existing UI, API, data, auth, dependency, and verification patterns before proposing a new one.
+2. Identify the decisions still unresolved after that evidence.
+3. Classify each unresolved decision:
+   - `repository_answerable`: inspect more local evidence instead of asking;
+   - `safe_assumption`: choose the smallest reversible option and state the assumption before or while
+     working;
+   - `blocking_question`: stop before implementation because the wrong choice would be expensive,
+     user-visible, security-sensitive, data-affecting, dependency-affecting, or hard to roll back.
+4. Ask about observable completion before feature shape when success is unclear:
+   - what behavior proves the task is done;
+   - which user path, command, test, screenshot, migration state, or registry/release state closes it.
+5. Ask about scope only when plausible scopes have different cost or risk:
+   - minimal symptom fix, root-cause fix, or broader cleanup;
+   - prototype, maintainable production path, or release-ready path.
+6. Ask about existing users and data before changing persistence, lifecycle, deletion, migration,
+   retention, cache, API compatibility, or old-client behavior.
+7. Ask about failure UX before implementing user-visible success flows where failure handling is a
+   product decision: retry, queue, message, audit/log-only, rollback, partial success, or manual
+   recovery.
+8. Ask about security and authorization before relying on UI hiding, client-side checks, roles,
+   invites, team boundaries, file access, billing state, or admin features.
+9. Ask before adding or swapping dependencies, services, queues, databases, auth providers, design
+   systems, state managers, or major folder boundaries.
+10. Ask about verification when there is no declared command intent or when the user expects a
+    specific proof beyond the repository's configured checks.
+11. Keep the question set short:
+    - ask at most three questions at once;
+    - each question must name the decision, the recommended choice, the consequence of that choice,
+      and one meaningful alternative;
+    - avoid open-ended prompts like "how should I implement this?" unless no responsible options can
+      be framed from repository evidence.
+12. If no blocking question remains, proceed without ceremony. State only the assumptions that matter
+    to review or rollback.
+13. If a blocking question remains unanswered, do not implement around it. Offer the smallest safe
+    non-blocked action, such as read-only analysis, a plan, a reproduction, or a narrow preparatory
+    refactor when another selected skill supports it.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Questions are grounded in inspected repository evidence.
+- The agent has not asked for facts it could read locally.
+- Expensive, user-owned, security-sensitive, data-affecting, dependency-affecting, and public-contract
+  decisions are resolved before implementation.
+- Safe assumptions are narrow, reversible, and reported.
+- The final work can be judged against observable success criteria or a reported verification gap.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `mustflow_check`
+
+This skill often runs before edits and may need no command execution by itself. After implementation,
+run the specific configured verification intents required by the selected implementation skills.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the user rejects a question as unnecessary, reclassify the decision as a safe assumption only
+  when current evidence supports a narrow reversible path; otherwise report the unresolved risk.
+- If new evidence shows the question was answered by current files, continue without asking and note
+  the evidence if it affects the final report.
+- If a blocking question reveals a larger feature, switch to the relevant skill before editing that
+  new scope.
+- If the task becomes over-scoped, reduce the next action to the smallest safe slice with explicit
+  acceptance evidence.
+- If verification intent is missing, report the missing command contract instead of inventing a raw
+  command.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Repository evidence inspected
+- Blocking questions asked, with recommendation and tradeoff
+- Safe assumptions made
+- Decisions intentionally deferred
+- Implementation scope selected
+- Command intents run
+- Skipped checks and reasons
+- Remaining ambiguity or rollback risk

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

@@ -108,6 +108,12 @@ route_type = "primary"
 priority = 20
 applies_to_reasons = ["unknown_change", "code_change"]
 
+[routes."clarifying-question-gate"]
+category = "general_code"
+route_type = "adjunct"
+priority = 42
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "migration_change", "package_metadata_change"]
+
 [routes."api-contract-change"]
 category = "general_code"
 route_type = "primary"
@@ -412,7 +418,7 @@ applies_to_reasons = ["code_change"]
 category = "general_code"
 route_type = "primary"
 priority = 35
-applies_to_reasons = ["code_change", "unknown_change"]
+applies_to_reasons = ["code_change", "unknown_change", "behavior_change", "public_api_change", "security_change", "data_change", "migration_change", "product_change"]
 
 [routes."repro-first-debug"]
 category = "bug_failure"

package/templates/default/locales/en/.mustflow/skills/structure-discovery-gate/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.structure-discovery-gate
 locale: en
 canonical: true
-revision: 27
+revision: 28
 lifecycle: mustflow-owned
 authority: procedure
 name: structure-discovery-gate
@@ -27,10 +27,18 @@ metadata:
 
 Find hidden structure decisions before coding so new files, folders, names, routing, data models, and integration boundaries reduce future change cost instead of producing a neat but brittle tree.
 
+This is the pre-implementation design gate for work where the agent might otherwise shrink the user's
+problem into an easy toy version. It should expose the agent's current understanding, classify the
+work by risk, and stop before coding only when the next design choice can change compatibility,
+data, authorization, failure behavior, scale, operations, or long-term structure.
+
 <!-- mustflow-section: use-when -->
 ## Use When
 
 - The task asks for a new feature, module, folder layout, architecture, scaffold, refactor, API integration, website, app flow, routing structure, data model, state model, or file split.
+- The user asks for a broad or ambiguous capability and coding immediately would require guessing
+  success criteria, scope boundaries, users or roles, data lifecycle, failure policy, scale target,
+  existing conventions, non-negotiable constraints, test proof, or operational recovery behavior.
 - A named technology or service may be only an implementation choice rather than the product domain, such as AdSense, Stripe, Supabase, Firebase, Resend, SendGrid, Google Analytics, Plausible, or a CMS.
 - The request may hide costly structural decisions around localization, SEO, authentication, authorization, payments, ads, analytics, admin workflows, deployment, content management, storage, retention, or external service replacement.
 - A website, content system, marketplace, comparison site, review site, knowledge base, documentation site, or data-backed product may later need filtering, search, localization, SEO, public APIs, apps, content revisions, data verification, redirects, or cache invalidation.
@@ -78,6 +86,10 @@ Find hidden structure decisions before coding so new files, folders, names, rout
 ## Required Inputs
 
 - User request and intended product or code change.
+- Design gate classification: `simple_patch`, `bounded_feature`, `structural_change`, or
+  `risk_change`, with a short reason for the classification.
+- The agent's current understanding of the requirement in four sentences or fewer.
+- Candidate success criteria, non-goals, and compatibility boundaries that could change the design.
 - Current project instructions, relevant context, and nearby implementation patterns when available.
 - Known target platform, language, framework, package, or deployment constraints.
 - Any named external services, content sources, user roles, locales, data stores, algorithms, policies, feature flags, or revenue surfaces in the request.
@@ -135,8 +147,32 @@ Find hidden structure decisions before coding so new files, folders, names, rout
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Restate the requested change as the product capability or code responsibility, not just the named technology.
-2. Identify hidden decisions that could change routing, folder names, file boundaries, data model, state ownership, environment variables, tests, deployment, SEO, localization, external integrations, or legal and policy requirements.
+1. Classify the work before designing:
+   - `simple_patch`: one obvious target, existing local pattern, low reversibility cost, no new
+     contract, data, permission, dependency, or architecture decision. Do not run a design interview;
+     inspect files and fix it.
+   - `bounded_feature`: a focused capability with a few missing product or verification decisions.
+     Produce a compact gate with at most five design-shaping questions.
+   - `structural_change`: new boundaries, data models, public contracts, workflows, services, or
+     cross-module responsibilities are likely. Do not edit until the design gate has a selected
+     implementation boundary.
+   - `risk_change`: the work touches database schema, auth, permissions, billing, personal data,
+     destructive actions, public APIs, migrations, dependencies on survival paths, external side
+     effects, or operational recovery. Treat editing as blocked until the risky decisions are
+     resolved or explicitly scoped out.
+2. Restate the requested change as the product capability or code responsibility, not just the named technology. Keep the restatement to four sentences or fewer so the user can correct an early misunderstanding quickly.
+3. Identify hidden decisions that could change routing, folder names, file boundaries, data model, state ownership, environment variables, tests, deployment, SEO, localization, external integrations, or legal and policy requirements.
+   Always check whether the design changes along these axes before asking:
+   - observable success criteria and verification proof;
+   - scope and non-scope, including public API, URL, schema, event, and stored-data compatibility;
+   - actor roles, tenant or ownership boundaries, and server-side authorization;
+   - data creation, state transition, deletion, retention, migration, and recovery lifecycle;
+   - failure mode, retry, idempotency, partial success, rollback, operator visibility, and manual recovery;
+   - expected scale, performance floor, pagination, indexing, caching, and queue or batch throughput;
+   - existing local conventions, nearby precedents, naming, error shapes, folder layout, and test style;
+   - constraints such as no new dependency, no migration, no public contract change, browser/runtime support, SEO, SSR, and privacy boundaries;
+   - tests or invariants that prove the behavior, not only happy-path examples;
+   - logging, metrics, audit, trace identifiers, alerts, and operational repair paths.
    For content-heavy products, treat these as structural decisions, not later feature polish:
    - Permanent identity: distinguish stable ids from titles, slugs, display names, routes, and provider ids.
    - Addressing: decide canonical URLs, locale routes, slug history, redirects, filter URLs, sitemap inclusion, `noindex`, and canonical behavior.
@@ -195,12 +231,15 @@ Find hidden structure decisions before coding so new files, folders, names, rout
    - Failure radius: decide timeout, retry, circuit-breaker, feature-flag, stale fallback, degraded mode, and resource-pool boundaries so one auxiliary dependency does not make unrelated core functions fail.
    - Operations: decide status workflow, ownership, created/updated actors, permissions, audit logs, preview needs, admin filters, analytics event identity, privacy, deletion, anonymization, retention, backup, and migration expectations before adding user or content data.
    - Interaction and monetization: decide whether accounts, anonymous identity linking, comments, moderation, reports, notifications, newsletter sends, paywalls, access levels, plans, and previews require data fields now even when the UI is deferred.
-3. Classify each decision:
+4. Classify each decision:
    - Blocking: the answer can change the basic structure and cannot be safely assumed.
    - Structure-impacting: the answer changes boundaries, but a conservative default can be stated if the user does not answer.
    - Preference: the answer affects styling, wording, or minor details and should not block structure.
-4. Ask at most five high-value questions before coding. Prioritize localization, authentication, authorization, payments, ads, personal data, destructive data actions, admin workflows, SEO, content storage, and external service replacement.
-5. For any question not asked, state the default assumption briefly. Defaults should keep future changes possible without adding speculative layers.
+5. Ask only questions whose answers can change the design. Each question must include the decision,
+   why it matters, the recommended default, and how at least one alternative changes the implementation.
+   Do not ask about facts that current files, docs, tests, schemas, or conventions can answer.
+6. Ask at most five high-value questions before coding. Prioritize localization, authentication, authorization, payments, ads, personal data, destructive data actions, admin workflows, SEO, content storage, external service replacement, failure policy, operational recovery, and verification proof.
+7. For any question not asked, state the default assumption briefly. Defaults should keep future changes possible without adding speculative layers.
    For a content or data-product default, prefer:
    - Stable internal ids plus mutable slugs.
    - Explicit lifecycle states and delete alternatives, such as archive, private, redirect, gone, and soft delete, before adding a destructive remove path.
@@ -254,7 +293,7 @@ Find hidden structure decisions before coding so new files, folders, names, rout
    - Operations-as-code-lite before infrastructure-as-code: even without Terraform or OpenTofu, require an environment schema, secret inventory, domain notes, cron definitions, deployment steps, observability notes, and smoke-test expectations when the platform can become a hidden source of truth.
    - Domain-shaped API responses over screen-shaped payloads; screen-specific endpoints are acceptable when labeled internal and still expose resources, states, errors, and pagination rather than card titles, button text, or storage implementation details.
    Do not add full implementations of these surfaces unless the task needs them now.
-6. Select structure patterns only when the task's risk shape requires them:
+8. Select structure patterns only when the task's risk shape requires them:
    - Use a plan/apply gate for destructive, bulk, migration, billing, permission, publishing, or external-send operations that need review before execution.
    - Use a capability object when a function should require a specific granted action instead of reading broad user or role state.
    - Use Result and Option values for expected business failures, meaningful absence, not found, invalid input, denied access, stale state, or blocked policy. Use `result-option` before editing that return-shape contract.
@@ -273,23 +312,23 @@ Find hidden structure decisions before coding so new files, folders, names, rout
    - Inject time or a time context when expiration, scheduling, retries, leases, or rate windows affect behavior.
    - Use explicit state transitions when three or more states have meaningful allowed moves.
    - Use an action ledger or idempotency key when repeating a side effect would be harmful.
-7. Prefer the smallest local version of the selected pattern. Do not add a framework, base class, service locator, global event bus, broad repository layer, or abstract factory when a plain function, table, adapter, or narrow policy object is enough.
-8. Separate product domains from vendor implementations. Use broad names at the product boundary and specific names inside provider or adapter internals.
+9. Prefer the smallest local version of the selected pattern. Do not add a framework, base class, service locator, global event bus, broad repository layer, or abstract factory when a plain function, table, adapter, or narrow policy object is enough.
+10. Separate product domains from vendor implementations. Use broad names at the product boundary and specific names inside provider or adapter internals.
    - Prefer `monetization/ads/providers/adsense` over top-level `adsense`.
    - Prefer `payments/providers/stripe` over top-level `stripe`.
    - Prefer `notifications/email/providers/resend` over top-level `resend`.
    - Prefer `analytics/providers/google-analytics` over top-level `googleAnalytics`.
-9. Propose the smallest folder and file structure that follows the answers and assumptions. For each new file or folder, state its responsibility and what it must not contain.
-10. Check the structure against local precedent with `pattern-scout` when the repository already has a nearby pattern.
-11. If the selected structure changes expected failure, meaningful absence, thrown business errors, null returns, or public error mapping, use `result-option` before editing that scope.
-12. If the selected structure creates or repairs a state-changing execution unit, use `command-pattern` before editing that scope.
-13. If the selected structure introduces or repairs lifecycle state transitions, use `state-machine-pattern` before editing that scope.
-14. If the selected structure introduces interchangeable algorithms, policies, calculations, provider choices, or feature-flag variants, use `strategy-pattern` before editing that scope.
-15. If the selected structure introduces one high-level entry point over several subsystem collaborators, use `facade-pattern` before editing that scope.
-16. If the selected structure separates business decisions from execution, use `pure-core-imperative-shell` before editing that scope.
-17. If the selected structure introduces inheritance, base classes, protected state, or subclass variants, use `composition-over-inheritance` before editing that scope.
-18. If the selected structure introduces or repairs an external dependency boundary, use `dependency-injection` for construction and collaborator flow, and `adapter-boundary` for external data, protocol, error, timeout, retry, idempotency, security, and observability handling.
-19. Implement only after the questions, assumptions, structure, dependency direction, and verification surface are clear enough for the task size.
+11. Propose the smallest folder and file structure that follows the answers and assumptions. For each new file or folder, state its responsibility and what it must not contain.
+12. Check the structure against local precedent with `pattern-scout` when the repository already has a nearby pattern.
+13. If the selected structure changes expected failure, meaningful absence, thrown business errors, null returns, or public error mapping, use `result-option` before editing that scope.
+14. If the selected structure creates or repairs a state-changing execution unit, use `command-pattern` before editing that scope.
+15. If the selected structure introduces or repairs lifecycle state transitions, use `state-machine-pattern` before editing that scope.
+16. If the selected structure introduces interchangeable algorithms, policies, calculations, provider choices, or feature-flag variants, use `strategy-pattern` before editing that scope.
+17. If the selected structure introduces one high-level entry point over several subsystem collaborators, use `facade-pattern` before editing that scope.
+18. If the selected structure separates business decisions from execution, use `pure-core-imperative-shell` before editing that scope.
+19. If the selected structure introduces inheritance, base classes, protected state, or subclass variants, use `composition-over-inheritance` before editing that scope.
+20. If the selected structure introduces or repairs an external dependency boundary, use `dependency-injection` for construction and collaborator flow, and `adapter-boundary` for external data, protocol, error, timeout, retry, idempotency, security, and observability handling.
+21. Implement only after the questions, assumptions, structure, dependency direction, and verification surface are clear enough for the task size.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -337,8 +376,12 @@ Also run narrower configured tests or builds required by the changed source, tem
 <!-- mustflow-section: output-format -->
 ## Output Format
 
+- Design gate classification and reason
+- Restated requirement in four sentences or fewer
 - Capability or responsibility being built
 - Blocking questions asked, or none
+- Recommended defaults and tradeoffs for each blocking question
+- Success criteria, non-goals, and compatibility boundaries
 - Structure-impacting assumptions
 - Proposed files and responsibilities
 - Upfront structure decisions versus deferred features

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.23.0"
+version = "2.25.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/clarifying-question-gate/SKILL.md",
   ".mustflow/skills/astro-code-change/SKILL.md",
   ".mustflow/skills/css-code-change/SKILL.md",
   ".mustflow/skills/dart-code-change/SKILL.md",
@@ -124,6 +125,7 @@ minimal = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",
@@ -175,6 +177,7 @@ patterns = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",
@@ -237,6 +240,7 @@ oss = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",
@@ -311,6 +315,7 @@ team = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",
@@ -373,6 +378,7 @@ product = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",
@@ -440,6 +446,7 @@ library = [
   "behavior-preserving-refactor",
   "code-review",
   "codebase-orientation",
+  "clarifying-question-gate",
   "astro-code-change",
   "css-code-change",
   "dart-code-change",