mustflow 1.15.97

package/templates/default/locales/en/.mustflow/skills/result-option/SKILL.md

@@ -0,0 +1,186 @@
+---
+mustflow_doc: skill.result-option
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: result-option
+description: Apply this skill when expected failures, meaningful absence, null or undefined returns, thrown business errors, boolean success flags, raw string errors, repository lookups, validation, parsing, external adapter errors, or boundary error mapping need explicit Result and Option handling.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.result-option
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Result / Option
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Represent expected failures and meaningful absence as explicit values.
+
+Use `Result<T, E>` when an operation can fail and the caller must know why. Use `Option<T>` when a value may be absent and absence is normal. Use `throw` only for programmer errors, impossible states, corrupted invariants, fatal startup failures, or third-party exceptions before an adapter converts them at a boundary.
+
+Expected failure must be data. Meaningful absence must be data. Exceptions are only for truly exceptional situations.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code throws for normal business failures such as validation failure, not found, permission denied, conflict, invalid state, expired token, insufficient balance, rate limit, timeout, payment rejection, or file validation.
+- Domain, application, or service functions return `null` or `undefined` to signal meaningful absence.
+- Code returns ambiguous success flags, optional error fields, raw string errors, or generic `Error` values.
+- A repository lookup can fail due to persistence and can also legitimately find no record.
+- External SDK, database, HTTP, payment, email, filesystem, or framework exceptions leak into business logic.
+- A controller, adapter, or command handler must convert typed failures into HTTP, UI, CLI, or queue responses.
+- Tests need stable success, failure, and absence cases without relying on thrown exceptions.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- A function is a total pure calculation that cannot fail and always returns a value; return `T` directly.
+- Absence is a bug because an invariant promises the value exists; use a stricter type or assert at the invariant boundary.
+- The task is only about separating decision logic from side effects; use `pure-core-imperative-shell`.
+- The task is only about provider mapping, timeout, retry, or protocol containment; use `adapter-boundary`.
+- Absence is an optional collaborator that can safely perform a neutral same-interface behavior without changing caller flow; use `null-object-pattern`.
+- The codebase already has a different established `Result` or `Option` shape and the task does not touch failure or absence handling.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The operation being modeled and whether it can fail, be absent, both, or neither.
+- Existing local `Result`, `Option`, error, `Either`, `Maybe`, exception, and response-mapping conventions.
+- The layer where failure originates and the layer where it should be handled.
+- Error categories, stable error codes, safe user-facing message rules, and sensitive data constraints.
+- Tests or examples that show successful, failing, and absent outcomes.
+- Relevant command-intent contract entries for verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Existing local result and option helpers have been searched before adding new helpers.
+- If external libraries or providers throw, `adapter-boundary` has been considered for conversion at that boundary.
+- If core logic currently performs I/O or logs while deciding failures, `pure-core-imperative-shell` has been considered.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace expected-failure `throw` paths with `Result<T, E>`.
+- Replace domain-level `null` or `undefined` absence with `Option<T>`.
+- Convert `Option<T>` to `Result<T, E>` at the point where absence becomes an error.
+- Add or reuse small discriminated-union helpers such as `ok`, `err`, `some`, `none`, `fromNullable`, `isOk`, `isErr`, `isSome`, `isNone`, `map`, `mapErr`, `andThen`, `matchResult`, `matchOption`, `fromPromise`, `okOr`, and `allResults` when local style supports them.
+- Add typed error unions, stable error codes, categories, and boundary mappers.
+- Add tests for success, failure, absence, error code, and error category.
+- Do not introduce a broad functional programming library unless the codebase already uses that style.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Choose the return shape.
+   - Return `T` when the value always exists and the operation cannot fail.
+   - Return `Option<T>` when absence is normal and needs no explanation.
+   - Return `Result<T, E>` when failure is expected and the caller must know why.
+   - Return `Promise<Result<T, E>>` for asynchronous expected failures.
+   - Return `Result<Option<T>, E>` when an operation can fail and success may still have no value.
+   - Return `Result<void, E>` for commands that can fail but have no useful success value.
+   - Use `throw` or `assertNever` only for impossible states, programmer errors, corrupted invariants, fatal startup failures, or test assertions.
+   - Use a null object only when the absence is an optional dependency with honest neutral behavior and the caller should not branch on presence.
+2. Keep expected failures out of exceptions.
+   - Do not throw for invalid input, missing resource, denied access, duplicate state, invalid transition, external timeout, rate limit, persistence failure, or payment rejection.
+   - Catch third-party exceptions in adapters and convert them to typed errors before they cross inward.
+3. Keep absence explicit.
+   - Domain, application, and service functions should not use `null` or `undefined` as meaningful absence.
+   - Raw DTOs, database rows, framework objects, and external API responses may contain `null` or `undefined`, but boundary mappers must convert them before they enter core logic.
+4. Use structured errors.
+   - Avoid raw string errors, generic `"ERROR"` codes, and optional error fields.
+   - Prefer stable machine-readable codes such as `INVALID_EMAIL`, `USER_NOT_FOUND`, `ORDER_ALREADY_PAID`, or `PAYMENT_PROVIDER_TIMEOUT`.
+   - Prefer consistent categories such as `validation`, `authentication`, `permission`, `not_found`, `conflict`, `invariant`, `rate_limit`, `timeout`, `external`, `persistence`, and `internal`.
+   - Keep raw causes, secrets, tokens, stack traces, SQL, payment payloads, and private user data out of public responses.
+5. Preserve specificity inside the system.
+   - Use narrow error unions close to the rule when practical.
+   - Widen to an application error type near use cases or boundaries.
+   - Preserve the underlying cause when useful, but do not make domain logic depend on third-party error classes.
+6. Compose results deliberately.
+   - Return, transform with `mapErr`, handle explicitly, or convert to a boundary response.
+   - Do not swallow `err` by returning success.
+   - Avoid nested results such as `Result<Result<T, A>, B>`; prefer `Result<T, A | B>`.
+   - Avoid `Result<Promise<T>, E>`; use `Promise<Result<T, E>>`.
+   - Prefer `Result<Option<T>, E>` over `Option<Result<T, E>>`.
+7. Use names that match meaning.
+   - Use `find*` when absence is normal.
+   - Use `get*` when absence is an error.
+   - Use `parse*`, `validate*`, and fallible `create*` functions when invalid input should produce `Result`.
+   - Use `is*`, `has*`, and `can*` only when a boolean answer is truly enough and cannot fail.
+8. Map at boundaries.
+   - Repositories that can fail and may not find data should return `Result<Option<T>, E>`.
+   - Services may convert an `Option` into a domain error when the value is required.
+   - Controllers, CLI handlers, queue consumers, and UI boundary code should convert `Result` into protocol responses.
+   - Do not serialize internal `Result` or `Option` shapes as public API responses unless that is the explicit public contract.
+9. Log once at the outer boundary.
+   - Do not log the same error at every layer.
+   - Pure domain functions must not log.
+   - Boundary logs may include category, code, safe details, and non-serialized cause according to privacy rules.
+10. Test the branches.
+    - Every `Result`-returning function should have tests for success, at least one representative failure, error code, error category, and important details.
+    - Every `Option`-returning function should have tests for `some` and `none`.
+    - Test stable codes and categories rather than complete free-form messages unless the message is a public contract.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Expected failures are represented as typed data.
+- Meaningful absence is represented as `Option` or the local equivalent.
+- Normal business failures do not rely on thrown exceptions or rejected promises.
+- Infrastructure and provider errors are converted at boundaries before reaching business logic.
+- Public responses expose stable safe error shapes, not internal `Result`, raw causes, secrets, or stack traces.
+- Tests cover success, failure, and absence branches.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer focused tests for the functions whose return shape or error handling changed. Use release or documentation checks when templates, public docs, package metadata, schemas, CLI behavior, or skill routing change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If local helper shape conflicts with this skill, follow the local convention and report the difference.
+- If replacing exceptions would require a broad public API change, narrow the change to one boundary and report remaining throw paths.
+- If error categories or codes are missing, add the smallest local error union or mapper instead of inventing a global taxonomy too early.
+- If a supposedly impossible condition can happen through user or system behavior, model it as `Result` instead of throwing.
+- If adapter conversion is incomplete, keep third-party error handling in the adapter and report remaining leakage.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Failure or absence surface changed
+- Return shape chosen and why
+- Error codes and categories introduced or reused
+- Boundary conversions added
+- Throw paths preserved and why
+- Tests added or updated
+- Command intents run
+- Remaining exception, null, or error-shape risks

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

@@ -0,0 +1,130 @@
+---
+mustflow_doc: skill.security-privacy-review
+locale: en
+canonical: true
+revision: 4
+lifecycle: mustflow-owned
+authority: procedure
+name: security-privacy-review
+description: Apply this skill when code, configuration, docs, templates, logs, telemetry, credentials, or data flows affect secrets, personal data, authentication, authorization, retention, or external disclosure.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.security-privacy-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Security and Privacy Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Catch security, privacy, and disclosure risks introduced by ordinary code, documentation, template, configuration, logging, or reporting changes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A change touches authentication, authorization, sessions, admin behavior, tenant boundaries, personal data, secrets, tokens, credentials, API keys, or private files.
+- A change adds or modifies logging, telemetry, diagnostics, receipts, reports, caches, generated state, retention, redaction, export, or external transmission.
+- Documentation, templates, examples, tests, or final reports mention sensitive data handling, privacy behavior, secret handling, or user-identifying data.
+- A diff could expose data through filenames, paths, command output, screenshots, generated artifacts, package contents, or public docs.
+- A change constructs, recommends, copies, resolves, or runs commands based on repository-controlled names, configuration, or generated reports.
+- A change reads or writes repository paths, follows filesystem links, packages files, or publishes release artifacts.
+- A workflow gains publish credentials, package registry identity, OIDC permissions, or third-party actions before artifact publication.
+- A code-scanning, Scorecard, CodeQL, zizmor, or dependency-scanning alert reports a security or quality issue that may cross a trust, disclosure, permission, or release boundary.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task needs a concrete abuse-case regression test; use `security-regression-tests` for that part.
+- The task is only dependency availability, package version freshness, or artifact packaging without sensitive data.
+- The task is a general security checklist with no changed boundary, data flow, or disclosure surface to inspect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Changed files, diff summary, and the user goal.
+- Sensitive data, actor, trust boundary, storage, logging, retention, export, or external disclosure surfaces involved.
+- Existing project rules for secrets, privacy, generated state, public docs, package contents, and command output.
+- Relevant command-intent contract entries for status, diff, docs, release, or mustflow validation.
+- Any repository-controlled names, paths, symlinks, command strings, environment path entries, workflow actions, or package contents that cross a trust boundary.
+- Scanner name, rule identifier, alert location, severity, data-flow evidence, and whether the alert is fixable in code or requires repository settings.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten redaction, masking, omission, retention, disclosure, or documentation wording when the changed surface justifies it.
+- Remove sensitive-looking sample values from docs, fixtures, templates, logs, reports, and final output when they are not required.
+- Mark unknown privacy or secret-handling behavior as unverified instead of claiming it is safe.
+- Do not invent compliance claims, privacy guarantees, secret scanning results, or audit coverage.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Identify the sensitive surface: secret, personal data, actor, permission, storage location, log, generated artifact, package file, public document, or external recipient.
+2. Decide whether the change creates, stores, reads, transforms, logs, exports, deletes, or reports sensitive information.
+3. Check whether the changed surface is public, packaged, generated, cached, retained, user-visible, or sent outside the repository boundary.
+4. Treat shell commands, copyable command text, executable names, workflow action references, publish identities, package manifests, and environment path entries as disclosure and execution surfaces, not as harmless strings.
+5. 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.
+6. 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.
+7. For workflow scanner alerts, check action pinning, `persist-credentials`, job-level permissions, reusable workflow permissions, artifact upload boundaries, and privileged identity timing before treating the warning as cosmetic.
+8. 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.
+9. 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.
+10. Verify that examples, fixtures, screenshots, command outputs, and final reports do not expose real-looking secrets or unnecessary personal data.
+11. Prefer omission or minimal metadata over masking when the sensitive value is not needed for the user to understand the result.
+12. If the change affects an authorization or abuse boundary, activate `security-regression-tests` for test selection instead of folding test generation into this review.
+13. Run the narrowest configured verification that covers the changed docs, templates, package, or mustflow contract.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Sensitive data and disclosure surfaces have been identified or explicitly reported as unknown.
+- Public and packaged surfaces do not include unnecessary secrets, personal data, or misleading privacy guarantees.
+- The final report names remaining unverified security or privacy risks without revealing sensitive values.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use a narrower configured test, build, or documentation intent when it better proves the changed sensitive surface.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a sensitive value appears in command output, stop copying it and summarize the issue without the value.
+- If the project lacks enough context to confirm privacy or secret handling, report the uncertainty and avoid claiming safety.
+- If a copyable command, executable lookup, symlink-following path, or publishing workflow uses repository-controlled input across a trust boundary, treat it as a security issue until quoting, validation, no-follow file handling, or workflow isolation is verified.
+- If a scanner reports many alerts from test fixtures or generated sample repositories, do not hide them by dismissal first. Prefer narrowing scanner inputs to the real release and runtime dependency surfaces, then document any intentionally scanned fixture exceptions.
+- If a package, generated artifact, or public doc includes sensitive data, remove or redact it before continuing unrelated work.
+- If verification requires unavailable scanners or live systems, report the missing check and the remaining risk.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Sensitive surfaces reviewed
+- Disclosure or retention paths checked
+- Redaction, omission, or wording changes made
+- Related security-regression test need
+- Command intents run
+- Skipped checks and reasons
+- Remaining security or privacy risk

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

@@ -0,0 +1,157 @@
+---
+mustflow_doc: skill.security-regression-tests
+locale: en
+canonical: true
+revision: 6
+lifecycle: mustflow-owned
+authority: procedure
+name: security-regression-tests
+description: Apply this skill when security-sensitive code or behavior changes need abuse-case regression tests.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.security-regression-tests
+  command_intents:
+    - test
+    - test_related
+    - test_audit
+    - lint
+    - build
+---
+
+# Security Regression Tests
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Convert security-sensitive behavior changes into safe negative tests that preserve defensive expectations without turning the task into vulnerability scanning, exploit development, or penetration testing.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Authentication, authorization, session, CSRF, rate-limit, admin, payment, credit, subscription, personal-data, or tenant-boundary behavior changes.
+- Input validation, output encoding, file upload, path handling, webhook callback, redirect, or external URL handling changes.
+- Command construction, command recommendation, executable resolution, command-contract linting, or copy-to-clipboard command behavior changes.
+- Filesystem containment, symlink handling, package publishing, build pipeline, or release automation behavior changes.
+- A bug fix closes an abuse case and the fix needs a regression test to prevent reintroduction.
+- A review identifies a concrete security-sensitive boundary that can be expressed as a deterministic test.
+- A static analysis alert identifies a concrete data flow, permission boundary, command boundary, artifact boundary, or input-handling bug that can be locked with a local test.
+- A repository health scanner flags missing fuzzing or property-based testing, and the project has a real parser, validator, serializer, path, command, or workflow boundary worth exercising with generated inputs.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only a general security review, dependency audit, static analysis request, or policy discussion.
+- The repository lacks enough application context to identify the real protected resource, actor, trust boundary, or existing test harness.
+- The only available output would be a generic test such as "prevents XSS" without a specific route, component, serializer, or data flow.
+- The test would require real external services, live attack traffic, credential guessing, destructive input, or unsafe payload collection.
+- The user explicitly asks not to add or propose tests.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The changed behavior, diff, route, component, handler, data model, or bug fix that creates the security-sensitive boundary.
+- The relevant actors, ownership rules, trust boundary, allowed and denied state combinations, and expected status or error behavior.
+- Existing test framework, fixtures, factories, mocks, request helpers, and naming conventions.
+- `.mustflow/config/commands.toml` entries for test, audit, lint, and build-related intents.
+- 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.
+- Existing fuzzing or property-based testing libraries, package metadata, lockfiles, and test-runner conventions when generated-input tests are added.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The test can be written as a defensive expectation without teaching an exploit recipe or contacting unsafe targets.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep edits within the scope described by this skill, the user request, and the matching route in `.mustflow/skills/INDEX.md`.
+- Prefer existing test files, fixtures, factories, mocks, and helper APIs before adding new test structure.
+- Do not broaden command permission, invent project facts, introduce external scanners, add offensive payload corpora, or change unrelated workflow files.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Identify the protected boundary: actor, resource, operation, trust boundary, and expected defensive outcome.
+2. Classify the abuse case using project-specific facts, not broad labels alone:
+   - unauthorized actor or cross-tenant access
+   - invalid ownership or privilege escalation
+   - unsafe input shape, size, encoding, path, or MIME mismatch
+   - unsafe output rendering or serialization
+   - unsafe external URL, callback, redirect, or server-side request target
+   - unsafe shell command construction, command name interpolation, clipboard command output, or executable lookup
+   - filesystem escape through symlinks, path traversal, archive entries, generated state, or package contents
+   - mismatch between two validators, linters, dashboards, schemas, or release gates that claim the same policy
+   - 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
+   - stack trace or internal error exposure through a user-visible API, report, dashboard, or command output
+   - workflow permission drift, mutable action references, wrong pinned-action object type, dependency scan overreach, or artifact credential leakage that can be checked through repository-local workflow tests or linters
+   - payment, credit, coupon, subscription, refund, or entitlement abuse
+   - personal-data or admin-only access leakage
+   - unsafe direct execution of destructive, bulk, migration, billing, permission, publishing, or external-send operations without a reviewable plan/apply boundary
+   - missing capability or scoped permission object where a sensitive operation depends on broad user, role, or global authorization state
+   - missing invariant policy where a sensitive state change could violate a non-negotiable rule such as last-owner, entitlement, paid-order, refund, or retention constraints
+   - missing idempotency key, action ledger, or outbox/inbox record where repeated execution of a side effect could charge, refund, notify, grant, revoke, publish, or delete more than once
+3. Search for existing tests that already cover the same boundary. Strengthen the existing test when that gives clearer coverage than adding a new one.
+4. Build the smallest safe negative test data: at least one allowed control case when useful, and one denied case that proves the boundary rejects the abuse condition.
+5. For parser, validator, serializer, path, command, or workflow boundaries, consider a bounded property-based or fuzz-style regression when the invariant is clearer than a list of hand-written examples. Keep generators local, deterministic under the test runner, size-limited, and focused on the defensive invariant.
+6. When adding a fuzzing or property-based testing dependency, keep dependency metadata, lockfiles, test selection rules, and package tests synchronized. Prefer an existing project dependency when it can express the invariant cleanly.
+7. Use mocks or local fakes for external requests, uploads, redirects, webhooks, payment providers, file systems, shell commands, package registries, and CI workflows. Do not contact live suspicious endpoints or publish real artifacts.
+8. Name the test after the defensive expectation, such as `cannot_read_other_users_invoice` or `rejects_private_network_callback_url`.
+9. Keep assertions tied to observable behavior: status code, returned error shape, unchanged database state, missing side effect, sanitized output, rejected job, or invariant preserved for all generated cases.
+10. Avoid dumping long exploit strings into the test. Use minimal representative inputs or generated values that prove the validation or boundary rule without becoming an offensive payload corpus.
+11. For command and filesystem boundaries, assert the denied side effect directly: no injected command appears in a runnable recommendation, no repository-local shim is executed, no background shell pattern is counted runnable, no symlink target outside the root is read or written.
+12. For plan/apply, capability, invariant, time, and idempotency boundaries, assert the safety contract directly: planning produces no side effect, commit rejects stale or unauthorized capability, invalid transitions preserve state, injected time controls expiry, and repeated side-effect keys do not repeat the effect.
+13. For workflow scanner fixes, prefer repository-local assertions for durable contracts: action references are pinned to commit SHAs or digest-pinned containers, privileged permissions are job-scoped, deployment or scanner jobs can be manually rerun when useful, and dependency scans exclude fixture-only manifests unless intentionally included.
+14. For scanner-driven fixes, include a regression only when the rule reflects a durable project contract. Do not add brittle tests that merely assert the scanner's current wording, line number, or severity.
+15. If the project lacks enough context to write a deterministic test, output a concrete test proposal instead of inventing fixtures or behavior.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The expected output can be produced with clear evidence, executed command intents, skipped checks, and remaining risks.
+- Any missing command intent, unknown input, or authority conflict is reported instead of hidden.
+- New tests are justified by a concrete security-sensitive behavior contract, not by a habit of adding tests to every change.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `test_related`
+- `test`
+- `test_audit`
+- `lint`
+- `build`
+
+Prefer the narrowest configured test intent that covers the changed boundary. Do not infer missing test, lint, scanner, or build commands. If a relevant intent is unknown or manual-only, report that status and the remaining verification risk.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a generated test fails because the defensive behavior is missing, inspect the nearest production code that owns the boundary before weakening the test.
+- If a generated test fails because fixtures or assumptions are wrong, fix the test setup or report the missing project fact.
+- If the test would require unsafe traffic, real credentials, live external targets, or destructive data, replace it with a local mock-based expectation or a written test proposal.
+- If existing tests already prove the boundary, report the existing coverage rather than adding duplicate cases.
+- If the repository's testing policy requires more evidence before adding tests, report the security-sensitive contract that justifies the test or stop at a proposal.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Security-sensitive boundary reviewed
+- Abuse case classification
+- Defensive structure selected, such as plan/apply, capability, invariant policy, adapter, injected time, or action ledger
+- Required test data
+- Tests added or strengthened
+- Property-based or fuzz-style invariant covered, if used
+- Existing coverage reused
+- Suspected code location if the test fails
+- Command intents run
+- Skipped command intents and reasons
+- Remaining security or verification risks

package/templates/default/locales/en/.mustflow/skills/skill-authoring/SKILL.md

@@ -0,0 +1,110 @@
+---
+mustflow_doc: skill.skill-authoring
+locale: en
+canonical: true
+revision: 5
+lifecycle: mustflow-owned
+authority: procedure
+name: skill-authoring
+description: Apply this skill when creating or maintaining `.mustflow/skills/*/SKILL.md` procedures and `.mustflow/skills/INDEX.md` routes.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.skill-authoring
+  command_intents:
+    - mustflow_check
+    - docs_validate
+---
+
+# Skill Authoring
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Create narrow, repeatable mustflow skill procedures without turning skills into broad advice, project context, or command-permission sources.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A `.mustflow/skills/<name>/SKILL.md` file is created, renamed, split, removed, or substantially changed.
+- `.mustflow/skills/INDEX.md` needs a new or updated route for a skill.
+- A skill needs clearer use conditions, exclusion conditions, required inputs, command intent references, verification, or failure handling.
+- A broad prompt, checklist, or outside recommendation needs to be adapted into mustflow's skill format.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only applies an existing skill to code, docs, tests, context, or assets.
+- The content belongs in `AGENTS.md`, `.mustflow/docs/agent-workflow.md`, `.mustflow/context/PROJECT.md`, or `.mustflow/config/commands.toml`.
+- The proposed skill is broad advice such as "write better code" or "be careful" without a repeatable trigger and procedure.
+- The skill would duplicate project-domain context, authorize commands, install dependencies, or define raw shell commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The user request and the repeated task the skill should cover.
+- Existing `.mustflow/skills/INDEX.md` and nearby skill documents.
+- `.mustflow/config/commands.toml` command intent names relevant to verification.
+- Any repository evidence showing that the task is repeatable and not better handled by an existing skill.
+- Localization and template metadata when the skill is part of an installed template.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep edits within the scope described by this skill, the user request, and the matching route in `.mustflow/skills/INDEX.md`.
+- Do not broaden command permission, invent project facts, or change unrelated workflow files.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Define the smallest repeatable task the skill should cover. If the task is too broad, split it or leave it as repository guidance instead of creating a skill.
+2. Search existing skills before adding a new one. Prefer updating a matching skill over creating overlapping procedures.
+3. Use a stable folder name and matching frontmatter `name`. Set `mustflow_doc` to `skill.<name>`, `metadata.mustflow_schema` to `"1"`, `metadata.mustflow_kind` to `procedure`, `metadata.pack_id` to the package namespace, and `metadata.skill_id` to `<pack_id>.<name>`.
+4. Write the standard sections: Purpose, Use When, Do Not Use When, Required Inputs, Preconditions, Allowed Edits, Procedure, Postconditions, Verification, Failure Handling, and Output Format.
+5. Keep the procedure concrete and bounded. Include what to read, what to change, what to avoid, and what evidence to report.
+6. Reference command intent names only. Do not include raw shell command blocks or claim that the skill authorizes command execution.
+7. Update `.mustflow/skills/INDEX.md` with a compact route that includes trigger, required input, edit scope, risk, verification intents, and expected output.
+8. If the skill is installed by a template, update template manifests, localization metadata, installation docs, package tests, and public docs that list installed files.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The expected output can be produced with clear evidence, executed command intents, skipped checks, and remaining risks.
+- Any missing command intent, unknown input, or authority conflict is reported instead of hidden.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `mustflow_check`
+- `docs_validate`
+
+If the skill changes tests or behavior-sensitive template output, also use the relevant configured test or build intents.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If `mustflow_check` reports missing sections, metadata drift, unknown command intents, raw shell commands, or command-permission claims, fix the skill contract before changing unrelated files.
+- If two skills overlap, tighten their use and non-use conditions or merge the duplicate procedure.
+- If a needed command intent is missing, record the missing intent instead of inventing a command inside the skill.
+- If translation confidence is low, keep the source skill authoritative and mark translations for review through template metadata.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Skill files added, updated, renamed, or removed
+- Skill index routes changed
+- Command intents referenced
+- Template or localization metadata updated
+- Command intents run
+- Skipped command intents and reasons
+- Remaining overlap, translation, or validation risks