mustflow 2.112.9 → 2.112.13

package/templates/default/locales/en/.mustflow/skills/observability-debuggability-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.observability-debuggability-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: observability-debuggability-review
@@ -94,79 +94,88 @@ The review question is not "does the code emit telemetry?" It is "when this path
    - List logs, metrics, traces, spans, events, audit entries, alerts, dashboards, runbooks, and exporter self-metrics touched by the path.
    - Mark each signal as symptom, cause evidence, correlation evidence, saturation evidence, recovery evidence, or noise.
    - A success-only log is not enough; failure classification and missing-work evidence matter more.
-3. Check metrics for numerator and denominator.
+3. Prefer trace-first diagnosis for distributed or cross-boundary failures.
+   - Compare normal and failing trace trees before reading only the final error log.
+   - Look for the first divergence in span order, missing span, retry branch, cache hit or miss, DB call count, dependency latency, worker shard, feature flag, release id, queue age, or pool wait.
+   - Logs should explain branch decisions inside that trace; metrics should show whether the incident is isolated or systemic.
+4. Align trace, log, and profiler evidence on one time axis when timing or ordering may matter.
+   - Trace evidence identifies the affected request, job, message, or operation.
+   - Profiler evidence identifies what the process was doing during the same window: CPU, wall wait, lock contention, allocation, GC, or pool wait.
+   - Do not treat a slow span as self-explanatory until the same window's process, pool, dependency, and queue evidence have been checked where available.
+5. Check metrics for numerator and denominator.
    - Error counters need total attempt counters so an operator can compute rates.
    - Cache hits need total lookups, fill errors, stale-served counts, origin latency, and eviction or lock-wait evidence when cache correctness matters.
    - Rate limits need allowed, blocked, shadow-blocked, delayed, retry-after, policy, and key-type evidence rather than only `rate_limited_total`.
-4. Reject average-only latency.
+6. Reject average-only latency.
    - Prefer histograms or equivalent distribution evidence for p95, p99, and tail behavior.
    - Separate success latency from error latency; fast failures should not make the service look healthy.
    - Label outcome and status class with bounded cardinality where the local metric system supports it.
-5. Protect metric cardinality.
+7. Protect metric cardinality.
    - Do not put raw URL paths, query strings, user ids, order ids, emails, message ids, idempotency keys, exception messages, SQL text, or arbitrary provider codes into metric labels.
    - Use route templates, dependency names, operation names, status classes, bounded reason enums, policy names, and feature flag names.
    - Keep high-cardinality fields in traces, structured events, audit records, or sampled logs when they are safe and needed for narrowing.
-6. Check trace and log correlation.
+8. Check trace and log correlation.
    - Logs should include trace id and span id, or the local equivalent, when distributed tracing exists.
    - Spans should include dependency name, operation name, route template, outcome, safe error type, retry attempt, timeout or cancellation class, and release or environment attributes when useful.
    - If a log line cannot be joined to a request, job, message, or batch run, it is weak incident evidence.
-7. Check async and queue context propagation.
+9. Check async and queue context propagation.
    - HTTP to worker, queue, stream, pub/sub, webhook, cron, and batch boundaries should propagate or intentionally fork trace context.
    - Producers should inject safe context into messages when the system needs end-to-end diagnosis; consumers should extract it before doing work.
    - A new trace at the worker boundary can be correct only when the handoff is intentionally modeled and linked by message, job, or causation id.
-8. Separate attempt from operation.
+10. Separate attempt from operation.
    - Retries should expose each dependency attempt and the final logical operation result.
    - A final success after two failed attempts is a business success and a dependency warning.
    - Record attempt number, max attempts, retry decision, delay, retry-after use, dependency name, and final exhaustion reason with bounded labels.
-9. Classify timeout, cancellation, and deadline.
+11. Classify timeout, cancellation, and deadline.
    - User cancellation, upstream deadline, server timeout, dependency timeout, pool acquire timeout, queue visibility expiry, and shutdown cancellation are different events.
    - Do not merge all of them into one generic error metric or log reason.
    - Preserve cancellation semantics without turning intentional caller cancellation into a dependency incident.
-10. Review external dependency spans and metrics.
+12. Review external dependency spans and metrics.
     - `GET https://api.vendor.example` is not enough; add a stable dependency name and operation name.
     - Track attempts, latency distribution, status class, retryable decision, timeout class, circuit-open decisions, and provider request id when safe.
     - Keep provider host, endpoint, and response details out of metric labels when they are unbounded or sensitive.
-11. Review database and transaction evidence.
+13. Review database and transaction evidence.
     - Avoid raw SQL in logs and telemetry where it can contain personal data or secrets.
     - Prefer query name, table or collection, operation, rows returned, rows affected, duration, timeout class, and safe error category.
     - Transaction flows should expose begin, commit, rollback, retry, after-commit side effects, external-call-before-commit risk, and compensation or reconciliation evidence when relevant.
-12. Review idempotency and partial-success evidence.
+14. Review idempotency and partial-success evidence.
     - Payment, order, entitlement, file, webhook, queue, and batch paths need idempotency key, dedupe key, message id, request id, attempt, side-effect state, and unknown-outcome markers where safe.
     - Ask where evidence remains when DB write succeeds but event publish fails, provider call succeeds but local state fails, cache write succeeds but origin rollback happens, or compensation fails.
     - Metrics and logs should distinguish attempt, success, failure, compensation, retry exhausted, and unknown outcome.
-13. Review queue, stream, and batch signals.
+15. Review queue, stream, and batch signals.
     - Consumers need queue delay or message age, processing duration, inflight count, ack or commit failures, redelivery count, retry count, DLQ count, poison reason, and oldest message age where supported.
     - Batch jobs need last success timestamp, last completion timestamp, duration, processed count, failed count, skipped count, and stale-job alert evidence.
     - Silent pipelines need heartbeat or synthetic item evidence when "no input" can look like success.
-14. Review pools and saturation.
+16. Review pools and saturation.
     - CPU can be low while worker, thread, DB connection, HTTP connection, queue, semaphore, or rate-limit pools are saturated.
     - Track active, max, queued, queue wait, acquire duration, timeout count, rejection count, and per-dependency pool names with bounded labels.
     - Missing saturation evidence should downgrade performance and reliability claims.
-15. Review feature, config, release, and migration attribution.
+17. Review feature, config, release, and migration attribution.
     - Logs, traces, and metrics should carry service version, git sha or release id, deployment environment, region, schema or migration version, config version, and relevant feature flag or experiment variant when local policy allows.
     - If a 5 percent feature flag cohort can fail separately, the telemetry must let operators split healthy and broken cohorts.
-16. Check alert and runbook usefulness.
+18. Check alert and runbook usefulness.
     - Every new critical metric should answer what panel, alert, or runbook sentence it supports.
     - Pager alerts should indicate user impact or clear operator action, not only "a counter changed."
     - Logs that page humans should have matching counters or rates so operators can see when the event started and how fast it is happening.
-17. Check telemetry self-observability.
+19. Check telemetry self-observability.
     - Exporters, collectors, custom metric collectors, log sinks, trace queues, and sampling pipelines need dropped, failed, queued, scrape error, and export latency evidence when they can blind operators.
     - If telemetry failure can hide product failure, treat missing self-metrics as an operational risk.
-18. Check signal pipeline loss and read-path visibility.
+20. Check signal pipeline loss and read-path visibility.
     - Compare produced, accepted, exported, stored, and query-visible signal counts when the path depends on logs, metrics, traces, or events for diagnosis.
     - Use canary events or synthetic heartbeats when "no telemetry" could mean no traffic, collector failure, broken parser, dropped queue, retention gap, or dashboard read failure.
     - Track event timestamp versus observed timestamp, queue oldest age, DLQ oldest age, parser or mapping failures by service and version, and duplicate or sequence-gap evidence.
     - Separate telemetry write-path health from read-path health. A sink can store data that dashboards cannot query, and dashboards can be healthy while new signals are not arriving.
     - If collector, sink, dashboard, or production telemetry checks are outside repository commands, report the manual-only boundary.
-19. Check sampling policy.
+21. Check sampling policy.
     - Head sampling can drop rare errors and slow traces.
     - Error, slow, retry-exhausted, high-latency, partial-success, DLQ, and compensation-failure traces often need keep rules, tail sampling, or explicit event evidence.
+    - If a rare failure can be sampled out, require fallback event logs for key span boundaries, duration, outcome, reason, tenant or job slice, feature flag, and deployment version.
     - If sampling is outside the repository, report the manual-only evidence boundary instead of assuming critical traces are retained.
-20. Check privacy before telemetry leaves the process.
+22. Check privacy before telemetry leaves the process.
     - Redact or classify tokens, passwords, authorization headers, cookies, raw bodies, emails, phone numbers, payment data, personal identifiers, prompt text, confidential document text, provider payloads, and full SQL before logger, metric, trace, baggage, or exporter entry.
     - Baggage should be small, safe, low-lifetime, and intentional. Do not use it as a general request metadata bag.
     - Report sink-side masking as insufficient when sensitive data can already leave the process unredacted.
-21. Require telemetry tests or contract evidence where feasible.
+23. Require telemetry tests or contract evidence where feasible.
     - Good tests assert stable event names, bounded label values, denominator counters, trace-context propagation, redaction, sampling flags, feature flag attributes, release attributes, and failure-category mapping.
     - Source-level guards can prevent raw URL or user id metric labels when runtime telemetry tests are not available.
     - If dashboards, alerts, production traces, or load evidence are manual-only, complete available checks and report the evidence gap.
@@ -176,6 +185,7 @@ The review question is not "does the code emit telemetry?" It is "when this path
 
 - The changed path has an incident question, signal ledger, metric model, trace and log correlation model, telemetry pipeline survival boundary, cardinality boundary, privacy boundary, and evidence level.
 - Missing denominators, average-only latency, success-only logs, uncorrelated logs, raw URL labels, raw user labels, raw SQL telemetry, lost async trace context, attempt and operation collapse, generic timeout or cancellation buckets, missing dependency names, missing queue age, missing batch last-success timestamp, missing pool saturation, missing release attribution, decorative metrics, unsafe baggage, telemetry self-blindness, and sampling that drops critical failures are fixed or reported.
+- Normal-versus-failing trace comparisons and trace/log/profiler time-axis alignment are used or reported as unavailable when timing, ordering, retry, queue, pool, or dependency behavior is the likely cause.
 - Observability claims are backed by configured tests, schema or fixture evidence, local telemetry conventions, dashboard or alert files, static review evidence, or labeled as manual-only or missing.
 
 <!-- mustflow-section: verification -->
@@ -208,7 +218,7 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 ## Output Format
 
 - Observability boundary reviewed
-- Incident question, signal ledger, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, signal pipeline survival, sampling, privacy, and test evidence findings
+- Incident question, signal ledger, normal-versus-failing trace comparison, trace/log/profiler time-axis alignment, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, signal pipeline survival, sampling, privacy, and test evidence findings
 - Observability fixes made or recommended
 - Evidence level: configured-test evidence, telemetry fixture evidence, dashboard or alert file evidence, static review risk, manual-only, missing, or not applicable
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/race-condition-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.race-condition-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: race-condition-review
-description: Apply this skill when code is created, changed, reviewed, or reported and shared state can be observed across interleaving execution flows, including check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, tryLock, timeout or retry behavior, cache miss fill, lazy initialization, atomics and memory ordering, database transaction races, uniqueness, distributed locks, idempotency, atomic file creation, event or outbox ordering, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
+description: Apply this skill when code is created, changed, reviewed, or reported and shared state can be observed across interleaving execution flows, including check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, tryLock, timeout or retry behavior, cache miss fill, lazy initialization, atomics and memory ordering, database transaction races, uniqueness, distributed locks, fencing tokens, idempotency state records, atomic file creation, event or outbox ordering, inbox or dedupe consumers, per-key serialization, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -59,7 +59,9 @@ The review question is not "does this code use threads?" The stronger question i
 - Interleaving points: `await`, I/O, database calls, callbacks, hooks, plugin calls, event publish, queue insert, lock release, timer scheduling, retry, cancellation, shutdown, close, send, and other function calls after a state read.
 - Synchronization boundary: lock scope, atomic operation, compare-and-swap, transaction, row lock, unique constraint, conditional update, singleflight, idempotency record, outbox, or file atomic create/rename behavior.
 - Ordering and duplication rules: event order, queue delivery semantics, duplicate messages, same-user or same-resource concurrency, retry replay, cancellation timing, timer overlap, and shutdown drain behavior.
+- Idempotency and ownership rule: business idempotency key, processing/succeeded/failed record state, duplicate-in-progress behavior, fencing token or generation owner, and whether same-key work is serialized while unrelated keys can run concurrently.
 - Evidence surface: existing tests, fixtures, schema constraints, command intents, logs, metrics, sequence numbers, request ids, transaction ids, versions, or manual-only concurrency evidence.
+- Incident file when a concurrency failure was observed: test name, seed, worker or thread count, scheduler settings, timeout, input, build hash, OS/runtime version, environment slice, and exact failure time when available.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -82,61 +84,68 @@ The review question is not "does this code use threads?" The stronger question i
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Name the shared fact. State the exact value or invariant another execution flow could change: balance, status, cache entry, uniqueness, queue offset, file existence, socket state, collection membership, timer owner, shutdown flag, or object ownership.
-2. Build a stale-read ledger.
+1. Preserve the incident file before changing code when a race was observed.
+   - Capture the failing test or workflow name, random seed, worker or thread count, scheduler or CPU-affinity setting when relevant, timeout, input, build hash, OS/runtime version, environment variables that affect scheduling, and exact failure time.
+   - Do not replace a missing incident file with "ran many times"; repeated passing runs are weaker than one reproducible failing condition.
+2. Name the shared fact. State the exact value or invariant another execution flow could change: balance, status, cache entry, uniqueness, queue offset, file existence, socket state, collection membership, timer owner, shutdown flag, or object ownership.
+3. Build a stale-read ledger.
    - For each shared state read, mark every later `await`, I/O, DB call, callback, event publish, queue insertion, lock release, timer, retry, cancellation, shutdown, close, send, or function call before the action.
    - Ask whether the read is still true after each interleaving point. If the answer relies on hope, the path is not race-safe.
-3. Catch check-then-act.
+4. Catch check-then-act.
    - Treat patterns such as `if exists then create`, `if balance >= amount then withdraw`, `if status == pending then approve`, duplicate email checks, coupon redemption, order number generation, and filesystem `exists` then `open` as unsafe until proven atomic.
    - Prefer atomic conditional updates, atomic create, insert with unique constraint, compare-and-swap, row locks, or file creation modes that fail when the target already exists.
-4. Catch read-modify-write.
+5. Catch read-modify-write.
    - `++`, `+=`, `push`, `append`, `map[key] = value`, collection mutation, get-then-set, and counter updates are shared-state writes, not harmless syntax.
    - Use atomic operations only when the invariant is one variable. If the invariant spans fields, rows, objects, or messages, use a transaction, lock, state machine, or conditional write that protects the whole fact.
-5. Do not trust a single event loop after `await`.
+6. Do not trust a single event loop after `await`.
    - In JavaScript, Python async, UI runtimes, and coroutine systems, a state read before `await` can be stale after the continuation resumes.
    - Re-read, validate a version, hold the correct synchronization boundary, or move the decision into an atomic operation.
-6. Review lock scope by invariant, not by field.
+7. Review lock scope by invariant, not by field.
    - A lock around one setter does not protect a multi-field or multi-row rule if reads and writes outside the lock can observe intermediate state.
    - Keep callbacks, hooks, events, plugin calls, external I/O, logging, JSON conversion, and long calculations outside locks unless the invariant truly requires them.
    - Define and follow a global lock order when more than one lock can be acquired.
-7. Treat `tryLock`, timeout, and retry as risk multipliers.
+8. Treat `tryLock`, timeout, and retry as risk multipliers.
    - Check what partial state remains when lock acquisition fails, times out, or is retried.
    - Verify rollback, idempotency, duplicate side-effect prevention, and retry budget. A retry can make a race rarer or louder, not correct.
-8. Review cache miss fill and lazy initialization.
+9. Review cache miss fill and lazy initialization.
    - Multiple misses for the same key should not all rebuild, fetch, insert, or publish the same value unless duplication is harmless and bounded.
    - Use singleflight, promise memoization with failure cleanup, once initialization, durable uniqueness, or explicit cache-authority rules.
    - Double-checked locking needs a memory-ordering story in runtimes where construction visibility is not automatically safe.
-9. Review atomics and memory ordering.
+10. Review atomics and memory ordering.
    - Atomics protect a specific operation on a specific value. They do not automatically make surrounding objects, arrays, maps, or multi-field invariants safe.
    - Check acquire/release or stronger memory ordering where the language exposes it, and report missing expertise or evidence instead of guessing.
-10. Review database races.
+11. Review database races.
     - A database transaction does not erase a race by itself. Check isolation level, row locks, predicate locks, uniqueness, conditional updates, and whether `SELECT` then `UPDATE` can be invalidated before commit.
     - Prefer `UPDATE ... WHERE status = ...`, insert-or-ignore/upsert with unique constraints, version columns, row locks, or serializable isolation when the invariant requires it.
     - Application-level duplicate checks are advisory only; unique facts belong in the database or another durable single-writer authority.
-11. Review distributed locks as debt.
-    - Lock expiry, process pauses, network delay, clock skew, and split ownership can let two workers believe they own the same work.
-    - Keep data correct if the distributed lock breaks: unique constraints, idempotency keys, fencing tokens, conditional writes, or state transitions should still reject stale owners.
-12. Review event, queue, and outbox ordering.
-    - Publishing an event before or after a state change can split the world unless a durable outbox or equivalent boundary ties them together.
-    - Queue consumers should assume duplicates, reordering, delayed delivery, redelivery after timeout, and concurrent work for the same user or resource.
-    - Use inbox deduplication, per-aggregate ordering, conditional state transitions, or idempotent side effects where needed.
-13. Review filesystem races.
+12. Review distributed locks as debt.
+   - Lock expiry, process pauses, network delay, clock skew, and split ownership can let two workers believe they own the same work.
+   - Keep data correct if the distributed lock breaks: unique constraints, idempotency keys, fencing tokens, conditional writes, or state transitions should still reject stale owners.
+13. Review event, queue, and outbox ordering.
+   - Publishing an event before or after a state change can split the world unless a durable outbox or equivalent boundary ties them together.
+   - Queue consumers should assume duplicates, reordering, delayed delivery, redelivery after timeout, and concurrent work for the same user or resource.
+   - Use inbox deduplication, per-aggregate ordering, per-key serialization, conditional state transitions, or idempotent side effects where needed.
+   - Same-key work should expose whether the current record is processing, succeeded, failed, cancelled, or dead. A duplicate arriving while the first attempt is still processing is not the same as replaying a completed result.
+   - Business idempotency keys should describe the intended operation, not just the transport request id, when retries or duplicate submissions must return the same logical result.
+14. Review filesystem races.
     - `exists` then `open`, temp file name selection, cleanup by path, and replace-in-place can race.
     - Prefer atomic create, safe temporary file APIs, same-directory temp files, fsync where durability matters, and atomic rename or replace semantics appropriate to the platform.
-14. Review shutdown, cancellation, timers, close, and send.
+15. Review shutdown, cancellation, timers, close, and send.
     - Shutdown should define who stops accepting work, who drains, who cancels, and who owns in-flight side effects.
     - Cancellation must be idempotent and safe when completion happens at the same time.
     - Timers and schedulers need one current owner; old timers should not update new state.
     - WebSocket, channel, stream, socket, queue, and emitter paths need a clear rule for close/send races and double close.
-15. Review shared collections and object reuse.
+16. Review shared collections and object reuse.
     - Iteration over a collection that another flow can mutate needs a lock, snapshot, immutable copy, version check, or concurrent collection semantics.
     - Object pooling, buffer reuse, mutable DTO reuse, and reused request contexts are unsafe if async work can still hold references.
     - Fake immutable objects with mutable internals, getters, shared maps, or cached arrays should be treated as mutable shared state.
-16. Review tests and logs with suspicion.
+17. Review tests and logs with suspicion.
     - `sleep`-based race tests are usually probability tests. Prefer deterministic barriers, fake schedulers, controlled promises, version assertions, unique constraints, or repeated stress only as supplementary evidence.
+    - Shake the schedule, not only the load: widen context-switch windows with configured deterministic barriers, fake schedulers, controlled yields, delay injection, or repeated stress harnesses only when the repository command contract allows them.
     - Logging can hide or change a race. Log order is not event order across threads, processes, async tasks, buffers, or machines.
-    - Use monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
-17. Escalate broad status fields into state-machine review.
+    - Use happens-before logs at handoff points such as queue push/pop, mutex unlock/lock, atomic release/acquire, promise/future completion, channel send/receive, callback registration/execution, plus monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
+    - Treat race detectors, thread sanitizers, deterministic record/replay, profilers, kernel tracing, or stress tools as configured or manual diagnostics only; never infer raw commands from the tool names.
+18. Escalate broad status fields into state-machine review.
     - If values such as `pending`, `processing`, `done`, `failed`, `cancelled`, `closed`, or `deleted` drive behavior, draw allowed transitions and reject stale concurrent transitions.
     - Use `state-machine-pattern` when the race fix needs a transition table, event union, transition log, retry reconciliation, or effect ordering.
 
@@ -144,9 +153,11 @@ The review question is not "does this code use threads?" The stronger question i
 ## Postconditions
 
 - Shared state reads, interleaving points, and stale-read risks are identified or ruled out.
+- Observed concurrency failures preserve the incident file needed to reproduce the same timing envelope when available.
 - Check-then-act and read-modify-write paths are atomic, guarded, constrained, or explicitly reported as residual risk.
 - Locks protect whole invariants, have a clear ordering rule, and avoid slow or reentrant work where possible.
 - Database, cache, queue, event, filesystem, cancellation, shutdown, timer, close/send, collection, and object-reuse races are checked where relevant.
+- Idempotency processing states, duplicate-in-progress behavior, fencing tokens, outbox/inbox handoffs, and per-key serialization are checked where relevant.
 - Tests or configured verification cover the highest-risk concurrency invariant when feasible.
 
 <!-- mustflow-section: verification -->
@@ -178,9 +189,11 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 ## Output Format
 
 - Shared state and invariant reviewed
+- Incident file captured or reported missing
 - Interleaving points checked
 - Check-then-act and read-modify-write findings
 - Async stale-read, lock scope/order, tryLock/timeout/retry, cache/lazy init, atomic/memory ordering, database transaction, uniqueness, distributed lock, idempotency, filesystem, event/outbox, queue, shutdown, cancellation, timer, close/send, shared collection, object reuse, fake immutable, test, log, and state-machine checks where relevant
+- Idempotency record states, fencing token, inbox or dedupe, per-key serialization, and duplicate-in-progress checks where relevant
 - Race fixes made or recommended
 - Tests or verification evidence
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/repro-first-debug/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.repro-first-debug
 locale: en
 canonical: true
-revision: 3
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: repro-first-debug
-description: Apply this skill when fixing a reported bug or confusing failure before the failure has a clear reproduction.
+description: Apply this skill when fixing, investigating, or instrumenting a reported bug, confusing failure, flaky symptom, production-only defect, unreproducible incident, or legacy-code failure before the failure has a clear reproduction.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -31,8 +31,9 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 ## Use When
 
 - A user reports a bug, broken behavior, confusing runtime result, or failed workflow.
-- A failure is visible, but the smallest reproduction path is not yet clear.
+- A failure is visible, intermittent, production-only, data-dependent, or reported from another environment, but the smallest reproduction path is not yet clear.
 - A fix could otherwise be based on speculation, stale assumptions, or a broad unrelated test run.
+- A safe temporary patch is needed to stop harm, but the change must also capture evidence for the next occurrence instead of only hiding the symptom.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -49,6 +50,8 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 - Any pasted error text, screenshot detail, failing command intent, route, or UI action.
 - Recently changed files or likely affected files.
 - Existing tests, command intents, or manual reproduction notes related to the failure.
+- Available diagnostic evidence such as trace id, span id, request id, job id, attempt, feature flag, deployment version, log query, normal-versus-failing trace comparison, profiler window, breakpoint or watchpoint condition, and safe DB/cache/external dependency facts.
+- Runtime state snapshot evidence when available: cache keys, DB row state, queue state, locks, in-flight work, timezone, environment/config values, server instance, feature flags, app version, browser/app version, region, release, and concurrent request count.
 - Any known flakiness, environment dependency, timing dependency, or unavailable reproduction requirement.
 
 <!-- mustflow-section: preconditions -->
@@ -81,13 +84,37 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
    - specific input, fixture, locale, path, or data shape;
    - external source, generated output, or stale build artifact.
    For each hypothesis, write the observation that would confirm or reject it before changing production code.
-6. If the symptom appears flaky, separate the reproducible behavior from the unstable trigger. Do not treat one passing broad rerun as proof that the issue is fixed.
-7. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
-8. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification.
-9. Apply the smallest fix that addresses the reproduced cause.
-10. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
-11. Add or keep a regression guard only when it is tied to the reproduced symptom or a directly observed boundary condition.
-12. Report the symptom, reproduction, hypotheses considered, observations, fix, original reproduction rerun, checks, and remaining risk.
+6. Reject symptom-cover patches before editing.
+   - A null check, timeout increase, expected-value tweak, broad retry, catch-and-ignore, or local-line-only patch is not acceptable until the broken invariant and first divergence are named.
+   - Before applying a patch, state which invariant failed, where the invariant first became false, and what no-patch observation proves that claim.
+   - List counterexamples that could still fail after the obvious patch, especially concurrency, cache, time zone, retry/idempotency, schema/wire compatibility, security, and performance cases.
+7. Build a diagnostic evidence packet when logs, traces, profiling, or breakpoints are involved.
+   - Prefer normal-versus-failing trace comparison before reading only the final error log.
+   - Tie evidence together with stable identifiers such as trace id, span id, request id, tenant id, job id, attempt, feature flag, and deployment version.
+   - If timing or ordering may matter, prefer profiler, trace duration, lock wait, allocation, queue age, or dependency latency evidence before stopping the process with a broad breakpoint.
+   - Use conditional instrumentation or breakpoints scoped to the failing id when configured or manually approved; do not leave those probes in committed code.
+8. If the symptom appears flaky, separate the reproducible behavior from the unstable trigger. Do not treat one passing broad rerun as proof that the issue is fixed.
+9. For unreproducible failures, switch from "make it fail locally" to "make the next failure leave evidence."
+   - Capture a state snapshot, not just the input payload: relevant memory/cache state, DB rows, locks, queue messages, time zone, deployment version, feature flags, environment/config values, server instance, dependency versions, and concurrency shape when safe and available.
+   - Prefer pre-failure ring buffers, bounded internal event trails, impossible-state assertions, invariant checks, DB constraints, background auditors, or sanity checkers that fire where the bad state is first created.
+   - Temporary mitigation should also add forensic evidence such as caller, retry header, idempotency key, first and second handling time, state before and after, or safe resource identifiers.
+10. Narrow production-only and legacy symptoms by evidence elimination.
+   - Split last-known-good and first-failed windows across code, config, data, migration, infra, dependency, external-provider, and traffic-pattern changes.
+   - Split mixed symptoms by error code, user cohort, browser, app version, region, server instance, time window, release, feature flag, and data shape before assuming one root cause.
+   - Search stable constants, error strings, DB column names, event names, queue topics, config keys, and external endpoint fragments before trusting function names.
+   - Start from exits and writers: DB writes, serialized responses, emitted events, emails, balance changes, files, queues, cron jobs, admin tools, and external side effects. Treat DB triggers, queues, cron, imports, and admin panels as code.
+   - Use blame, linked commits, PRs, and same-commit file changes for historical context, not for assigning fault.
+11. Stress hidden conditions deliberately when the repository has a configured or approved way to do so.
+   - Suspect time, randomness, and concurrency first for "sometimes" failures.
+   - Prefer fixed seeds, fake clocks, forced interleavings, latency injection, duplicate or reordered messages, worker kills, cache clears, slight time shifts, and concurrent requests over waiting for chance.
+   - Minimize production data into a safe fixture by removing unrelated rows or events until the trigger disappears, then restore the last removed condition.
+12. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
+13. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification unless the user explicitly wants durable diagnostics.
+14. Apply the smallest fix that addresses the reproduced or instrumented cause. Keep behavior-preserving cleanup, characterization tests, bug fixes, and long-term refactors separate when the codebase is legacy or high-risk.
+15. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
+16. For unreproducible fixes, define the "fixed" metric before claiming success: failure rate, invariant violation count, duplicate handling count, retry exhaustion count, DLQ growth, timeout rate, latency tail, or another symptom-specific measure.
+17. Add or keep a regression guard only when it is tied to the reproduced symptom, the instrumented invariant, or a directly observed boundary condition.
+18. Report the symptom, reproduction, hypotheses considered, observations, evidence packet, fix, original reproduction rerun, checks, and remaining risk.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -95,6 +122,10 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 - The final report distinguishes reproduced evidence from assumptions.
 - Any added test or reproduction note is tied to the reported failure, not to general coverage growth.
 - Cause hypotheses are confirmed, rejected, or left explicitly unresolved instead of being implied by a passing broad check.
+- Symptom-cover patches are rejected unless they repair the named invariant and survive relevant counterexamples.
+- Trace, log, profiler, breakpoint, DB, cache, and dependency evidence is correlated by stable identifiers when that evidence exists.
+- Unreproducible defects are handled with next-failure evidence capture, state snapshots, bounded event trails, impossible-state monitors, and pre-declared fix metrics rather than a speculative local patch.
+- Legacy-code investigations start from symptom exits, writers, stable strings, data flow, history, and code-outside-code surfaces before broad call-graph reading or cleanup.
 - Temporary instrumentation and debug output are removed before final verification unless intentionally retained.
 - Missing command intents, unavailable tools, or unsafe reproduction requirements are reported instead of hidden.
 
@@ -125,6 +156,8 @@ Prefer the original failing intent when it is narrower than the defaults above.
 - Symptom and expected behavior
 - Reproduction path or reproduction gap
 - Hypotheses considered and observations
+- Diagnostic evidence packet and counterexamples considered
+- State snapshot, next-failure capture, last-good or first-failed window, symptom split, and legacy narrowing evidence where relevant
 - Probable cause, confidence, and evidence
 - Fix applied
 - Original reproduction rerun result

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

@@ -790,7 +790,7 @@ applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_
 category = "data_external"
 route_type = "primary"
 priority = 75
-applies_to_reasons = ["code_change", "docs_change", "security_change", "package_metadata_change", "release_risk"]
+applies_to_reasons = ["code_change", "docs_change", "security_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."dependency-reality-check"]
 category = "data_external"
@@ -814,7 +814,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "docs_c
 category = "data_external"
 route_type = "adjunct"
 priority = 65
-applies_to_reasons = ["code_change", "security_change", "migration_change"]
+applies_to_reasons = ["code_change", "security_change", "migration_change", "package_metadata_change", "release_risk"]
 
 [routes."adapter-boundary"]
 category = "data_external"
@@ -886,7 +886,7 @@ applies_to_reasons = ["test_change"]
 category = "security_privacy"
 route_type = "primary"
 priority = 30
-applies_to_reasons = ["security_change", "privacy_change"]
+applies_to_reasons = ["security_change", "privacy_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."secret-exposure-response"]
 category = "security_privacy"
@@ -934,7 +934,7 @@ applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "publi
 category = "security_privacy"
 route_type = "adjunct"
 priority = 76
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "package_metadata_change", "release_risk"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "docs_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."security-regression-tests"]
 category = "security_privacy"

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.security-flow-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: security-flow-review
-description: Apply this skill when code is created, changed, reviewed, or reported and security review needs source-to-sink tracing across authorization, object ownership, tenant scoping, IDOR or BOLA risk, mass assignment, admin-only surfaces, cache keys, exports, injection-like inputs, ORM raw paths, SSRF, file upload and extraction, path traversal, XSS, CSRF, OAuth, reset tokens, JWTs, cookies, cryptography, logs, fail-open error handling, async jobs, race conditions, or supply-chain and CI/CD paths.
+description: Apply this skill when code is created, changed, reviewed, or reported and security review needs source-to-sink tracing across authorization, object ownership, tenant scoping, IDOR or BOLA risk, mass assignment, admin-only surfaces, cache keys, exports, injection-like inputs, ORM raw paths, SSRF, file upload and extraction, path traversal, development server file serving, privileged test or browser UI APIs, XSS, CSRF, OAuth, reset tokens, JWTs, cookies, cryptography, logs, fail-open error handling, async jobs, race conditions, or supply-chain and CI/CD paths.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -42,7 +42,8 @@ changes, and where can data or authority leak?"
 
 - Code review, implementation, or report work touches routes, handlers, services, repositories,
   resolvers, jobs, workers, admin tools, exports, imports, caches, files, external fetchers,
-  OAuth callbacks, tokens, cookies, logs, CI workflows, package metadata, or dependency execution.
+  OAuth callbacks, tokens, cookies, logs, CI workflows, package metadata, development servers,
+  test UI servers, browser-mode tooling, preview servers, or dependency execution.
 - A feature accepts an identifier, URL, filename, path, HTML, Markdown, sort key, filter, field list,
   status, role, price, entitlement, tenant id, organization id, user id, or client-provided state.
 - The suspected issue may be BOLA, IDOR, missing authorization, tenant leak, mass assignment,
@@ -76,7 +77,8 @@ changes, and where can data or authority leak?"
 - Read and write surfaces: list, detail, count, export, download, search, stats, update, delete,
   approve, invite, upload, webhook, callback, job, and admin paths.
 - Framework or platform escape hatches: raw query APIs, shell wrappers, HTML escape bypasses, file
-  APIs, URL fetchers, parser options, cache behavior, token libraries, and CI/package lifecycle hooks.
+  APIs, URL fetchers, parser options, cache behavior, token libraries, development-server host and
+  filesystem policies, privileged test UI APIs, and CI/package lifecycle hooks.
 - Existing tests, denial cases, scanner findings, security docs, command intent entries, and any
   missing context that blocks a confident conclusion.
 
@@ -172,6 +174,11 @@ changes, and where can data or authority leak?"
     - Locale files, templates, themes, attachments, logs, static proxies, backup restore, plugin
       loaders, model loaders, and generated state all need real-path containment after symlinks and
       normalization.
+    - For framework file-serving and dev-server APIs, trace URL path, query string, raw path,
+      decoded path, normalized path, denied path, and final opened file as separate values. Windows
+      alternate data streams, device namespace prefixes, 8.3 short names, mixed separators, and
+      trailing dot or space aliases can make a lexical allow/deny check protect a different name
+      than the operating system opens.
 16. Trace browser-code execution contexts.
     - XSS can enter through Markdown, rich text, translations, email templates, chart labels, admin
       dashboards, CSV exports, hydration data, JSON-in-script blocks, and framework escape hatches.
@@ -213,6 +220,11 @@ changes, and where can data or authority leak?"
     - Dependency manifests, lockfiles, postinstall scripts, codegen, Docker base images, GitHub
       Actions permissions, workflow triggers, artifact upload, CI secrets, package publish identity,
       Terraform modules, Helm charts, and deployment scripts can execute or leak authority.
+    - Treat exposed dev servers and test UIs as execution surfaces when they can rerun tests, write
+      snapshots or source files, save attachments, read arbitrary files, or execute browser-mode
+      commands. Binding such a server to `0.0.0.0`, a LAN host, a tunnel, a container-published
+      port, or a remote workspace turns local convenience APIs into remote authority unless explicit
+      read-only, no-write, and no-exec gates are enforced.
 25. Convert the finding into the smallest defensive action.
     - Fix the owner closest to the sink when the boundary is clear.
     - If evidence is incomplete, report the exact unverified source, sink, actor, resource, tenant,
@@ -229,6 +241,8 @@ changes, and where can data or authority leak?"
   wording.
 - Security-sensitive caches, workers, queues, logs, tokens, files, browser renderers, and CI/CD paths
   are either checked or explicitly reported as outside the current evidence.
+- Development-server and test-UI file read, write, rerun, attachment, snapshot, and execute surfaces
+  are checked when the dependency, config, or scanner finding points at them.
 - Any concrete security bug fix has denial-case or invariant evidence, or the missing test surface is
   reported.
 
@@ -272,6 +286,7 @@ Prefer the narrowest configured test intent that proves the reviewed defensive b
 - Authorization and ownership notes
 - Input, file, network, browser, token, cookie, crypto, log, fail-open, async, race, cache, and
   supply-chain findings when relevant
+- Development-server and test-UI exposure findings when relevant
 - Fixes made or recommendation
 - Tests, denial cases, or invariant evidence
 - Command intents run

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.security-privacy-review
 locale: en
 canonical: true
-revision: 23
+revision: 24
 lifecycle: mustflow-owned
 authority: procedure
 name: security-privacy-review
-description: Apply this skill when code, configuration, docs, templates, logs, telemetry, traces, baggage, behavior analytics, core events, credentials, data flows, data residency policy, region or processing-location claims, AI-generated code, AI prompts outputs usage cost records budgets policies or cache keys, authentication, authorization, server-side permission checks, admin operations, audit logs, file uploads or downloads, signed URLs, API responses, cache policy, cache-as-authority decisions, claim or policy data, comparison or affiliate data, user-generated content, webhooks, job queues, search logs, analytics SaaS exports, external API call records, network calls, dependencies, runtime security patch policy, third-party terms or data-use promises, cryptography, secure transport, agent configuration, or release surfaces affect secrets, personal data, retention, access control, vendor disclosure, or external disclosure.
+description: Apply this skill when code, configuration, docs, templates, logs, telemetry, traces, baggage, behavior analytics, core events, credentials, data flows, data residency policy, region or processing-location claims, AI-generated code, AI prompts outputs usage cost records budgets policies or cache keys, authentication, authorization, server-side permission checks, admin operations, audit logs, file uploads or downloads, signed URLs, API responses, cache policy, cache-as-authority decisions, claim or policy data, comparison or affiliate data, user-generated content, webhooks, job queues, search logs, analytics SaaS exports, external API call records, network calls, dependencies, runtime security patch policy, vulnerability scanner advisories, development servers, test UI servers, third-party terms or data-use promises, cryptography, secure transport, agent configuration, or release surfaces affect secrets, personal data, retention, access control, vendor disclosure, or external disclosure.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -40,6 +40,7 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 - A tool, platform, model provider, analytics service, observability vendor, authentication provider, file store, or automation service has data retention, data training, commercial-use, export, API-limit, account-suspension, or unilateral terms-change implications for user data or service continuity.
 - A cloud, database, file store, logging backend, analytics tool, support tool, payment system, or AI provider choice affects where customer content, personal data, backups, logs, prompts, usage metadata, billing metadata, or support-access data is stored or processed.
 - A runtime, framework, dependency, or platform choice affects supported-version policy, end-of-life exposure, security patch timing, scanner coverage, deployment smoke tests, or rollback expectations.
+- A development server, preview server, browser-mode test server, or local tool UI can serve files, expose an API, execute tests, write project files, or bind beyond localhost.
 - A change touches administrator operations such as publishing, slug or redirect changes, canonical or robots changes, SEO updates, filter definition updates, advertisement policy, cache purge, search reindexing, ranking refresh, role changes, or audit-log snapshots.
 - A change touches legal, policy, privacy, finance, health, comparison, ranking, price, eligibility, affiliate, or high-risk factual claims that need source, reviewer, jurisdiction, effective-date, or human-approval boundaries.
 - A change touches identity, consent, editorial, catalog, community, analytics, billing, messaging, or audit data ownership boundaries, including account deletion, anonymization, export, or retention behavior.
@@ -93,6 +94,7 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 - Data residency and processing-location policy, including home region, storage region, backup region, log region, analytics region, AI processing region, support-tool region, payment or tax data region, disaster-recovery replica region, deletion expectations, and whether provider system data is outside customer-content residency guarantees.
 - Data classification policy when available, including sensitive personal data, ordinary personal data, product usage data, public content, AI prompts or outputs, and which classes may enter logs, analytics, support tools, AI providers, or cross-region backups.
 - Runtime and dependency patch policy, including supported or LTS version requirement, end-of-life ban, lockfile expectation, vulnerability scan source, patch response target, smoke-test surface, canary or rollback route, and whether experimental runtime choices are kept off survival paths.
+- Development-tool exposure policy, including host binding, allowed network interfaces, file-serving roots, deny lists, privileged API flags, write or execute capabilities, token handling, and whether the tool is local-only or safe for shared networks.
 - Webhook and external-call record policy, including signature verification, processed-event deduplication, safe request hashes, redacted provider responses, unknown-result reconciliation, dead-letter retention, and whether raw payloads are needed or should be replaced by bounded metadata.
 - Public intake default policy, including whether verifiers, authenticators, authorizers, deduplication stores, idempotency stores, and normalizers are required by registration, explicit opt-in, or silently replaced by permissive defaults.
 - Attacker-controlled key and header limits for idempotency keys, webhook event ids, provider names, action names, replay ids, dedupe keys, request ids, and any in-memory map or queue keyed by public request data.
@@ -198,10 +200,12 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 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.
     - For lockfile CVEs, inspect the manifest and lockfile together. Identify the direct parent that keeps the vulnerable transitive package in the graph, update the narrowest direct dependency or override needed to reach the fixed range, and confirm the vulnerable package version no longer appears in the resolved graph before claiming the alert is fixed.
+    - For advisories involving development tools such as Vite, Vitest UI, browser-mode test servers, Storybook, docs preview, asset servers, or framework dev servers, do not dismiss the issue merely because the package is a devDependency. Check whether scripts, docs, Docker, Codespaces, CI previews, tunnels, or config bind the server to a non-localhost host, widen file-serving roots, disable deny lists, or expose privileged read, write, rerun, snapshot, attachment, or execute APIs.
 37. For deployment settings, check debug mode, sample admin accounts, default credentials, public admin panels, open metrics endpoints, public storage, root container users, HTTPS enforcement, and exposed GraphQL or development consoles.
 38. For runtime and framework security updates, check that supported versions are documented, end-of-life versions are rejected, dependency locks exist where appropriate, security patches can be tested and deployed quickly, and rollback or redeploy can happen without manual dashboard memory. Do not treat a fashionable or high-performance runtime as safe unless the patch path is operationally credible.
+    - Treat advisory exploit preconditions as review inputs, not excuses. If the exploit requires Windows, NTFS alternate data streams, 8.3 short names, non-localhost binding, exposed QUIC or SSH clients, oversized public keys, malformed protocol frames, or misbehaving peers, search for those conditions before marking the alert irrelevant.
 39. For transport security, check HTTPS/TLS requirements, certificate validation, insecure HTTP downgrade paths, disabled verification flags, and whether sensitive traffic can bypass the secure channel.
-40. For cryptography, reject custom cryptography and tutorial-grade shortcuts. Check password hashing uses a password-hashing primitive such as bcrypt, scrypt, or Argon2id where supported by the project; random tokens use secure randomness; keys are separated from encrypted data; and weak hashes such as MD5, SHA-1, or bare SHA-256 are not used for password storage.
+40. For cryptography and security protocols, reject custom cryptography and tutorial-grade shortcuts. Check password hashing uses a password-hashing primitive such as bcrypt, scrypt, or Argon2id where supported by the project; random tokens use secure randomness; keys are separated from encrypted data; weak hashes such as MD5, SHA-1, or bare SHA-256 are not used for password storage; protocol parsers bound attacker-controlled key sizes, packet sizes, frame ordering, unsolicited responses, and panic or assertion paths.
 41. For policy engines, architecture linters, compliance validators, and generated governance gates, identify the canonical policy source and the canonical object identity before trusting a pass result.
     - Do not let repository-controlled advisory fields, nested duplicates, labels, components, owners, stages, tiers, or exemption fields override a trusted catalog, server-derived identity, or central registration.
     - When two fields can describe the same security decision, such as top-level and nested owner values, validate their consistency or choose the canonical source explicitly instead of reading the first convenient path.
@@ -276,6 +280,7 @@ Use a narrower configured test, build, or documentation intent when it better pr
 - Data residency, data classification, AI processing location, runtime patch, and hard-limit policy checked when relevant
 - Claim, comparison, affiliate, user-generated content, data-ownership, deletion, anonymization, export, and retention boundaries checked when relevant
 - Authorization, session, token, input, file, network, business-logic, dependency, cryptography, transport, deployment, scanner, and agent-tool boundaries checked
+- Development-server, test-UI, scanner-advisory, Windows filesystem, protocol parser, and dependency patchability boundaries checked when relevant
 - Permission exception and emergency-access boundaries checked when relevant
 - Redaction, omission, or wording changes made
 - Related security-regression test need

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

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 20
+revision: 21
 lifecycle: user-editable
 authority: binding
 ---
@@ -57,6 +57,11 @@ mustflow-managed details are under `.mustflow/`.
   and command specification.
 - Preferences in `.mustflow/config/preferences.toml` have lower priority than direct user
   instructions and existing project style.
+- If this repository is a child repository without its own `.mustflow/config/preferences.toml`,
+  inherit the nearest parent mustflow root's preferences as defaults. This includes `[git]`,
+  `[git.commit_message]`, `[release.versioning]`, verification, testing, language, reporting, and
+  other preference sections. Child-local preferences override parent preferences field by field.
+  Never inherit `.mustflow/config/commands.toml`; command authority remains repository-local.
 - When code, templates, schemas, CLI behavior, package metadata, user-visible docs, installation
   output, or tests change, check `[release.versioning]` in `.mustflow/config/preferences.toml`
   before the final report. Version files may be changed only according to those preferences:
@@ -115,6 +120,9 @@ 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.
+- If the nested repository has no local preferences file, apply the nearest parent mustflow
+  preferences as inherited defaults while still following the nested repository's `AGENTS.md` and
+  command contract.
 - 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