@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/skills/fec-refactoring-move-features/references/moving-refactorings.md

@@ -0,0 +1,453 @@
+# Moving Feature Refactorings
+
+These cards transform the supplied standard catalog into concise operational guidance for frontend agents. Standard IDs/names are preserved; examples and framework adaptations are original.
+
+## RF-MOVE-FUNCTION — Move Function
+
+### Intent
+Move behavior to the module that owns most of the data it uses or the responsibility it represents.
+
+### Typical Signals
+- A function depends more on another module’s data than its current home.
+
+### Avoid When
+- Do not move orchestration merely because it calls several collaborators; coordination may be its responsibility.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify data ownership and change responsibility.
+2. Create/copy the function at the destination with a narrow interface.
+3. Delegate from the old location while migrating callers.
+4. Remove the old location only when dependencies and public contracts permit.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-DIVERGENT-CHANGE`
+- `SMELL-SHOTGUN-SURGERY`
+- `SMELL-FEATURE-ENVY`
+- `SMELL-TEMPORARY-FIELD`
+- `SMELL-MESSAGE-CHAINS`
+- `SMELL-INSIDER-TRADING`
+- `SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES`
+- `SMELL-DATA-CLASS`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: a component-local mailbox quota calculation mostly reads account policy data. After: move it to the account policy module and keep UI code declarative.
+
+## RF-MOVE-FIELD — Move Field
+
+### Intent
+Move data to the object/module that conceptually owns it and changes with it.
+
+### Typical Signals
+- A field is read/updated mainly by another owner or repeatedly travels with another data cluster.
+
+### Avoid When
+- Avoid moving a public serialized field without a compatibility plan.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the real owner and all reads/writes.
+2. Add storage/access at the destination.
+3. Redirect reads and writes incrementally.
+4. Remove old storage after state synchronization is no longer required.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-SHOTGUN-SURGERY`
+- `SMELL-INSIDER-TRADING`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: a view controller owns `quotaLimit` though policy service controls it. After: policy owns the field and UI reads through the policy boundary.
+
+## RF-MOVE-STATEMENTS-INTO-FUNCTION — Move Statements into Function
+
+### Intent
+Move statements that always accompany a function call into that function so the shared operation is complete.
+
+### Typical Signals
+- The same setup/teardown statement appears around many calls and belongs to the called operation.
+
+### Avoid When
+- Do not move caller-specific policy into a generic function.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Find repeated adjacent statements around the call.
+2. Move one shared statement into the callee.
+3. Verify callers and ordering.
+4. Repeat only for behavior truly common to all callers.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: every caller formats a draft ID immediately before `saveDraft`. After: `saveDraft` owns canonical ID formatting if it is always required.
+
+## RF-MOVE-STATEMENTS-TO-CALLERS — Move Statements to Callers
+
+### Intent
+Move behavior out of a function when only some callers need it or its policy varies by context.
+
+### Typical Signals
+- A formerly common step is now caller-specific.
+
+### Avoid When
+- Avoid duplicating logic when the behavior is still a stable invariant of every caller.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the statement whose policy varies.
+2. Expose or split the callee so callers can perform the varying step.
+3. Move the statement to one caller at a time.
+4. Verify ordering and shared invariants.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: `loadMessages` always shows a toast, but background refresh must not. After: callers decide whether to notify after loading.
+
+## RF-REPLACE-INLINE-CODE-WITH-FUNCTION-CALL — Replace Inline Code with Function Call
+
+### Intent
+Use an existing function instead of duplicating equivalent inline logic.
+
+### Typical Signals
+- Inline logic already has a trustworthy named implementation elsewhere.
+
+### Avoid When
+- Do not replace merely similar logic when semantics or edge cases differ.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Prove equivalence between inline code and the existing function.
+2. Replace one occurrence with the call.
+3. Verify result, error, and evaluation semantics.
+4. Remove any now-unused local helpers.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: an inline loop checks whether a folder is special. After: call the existing `isSpecialFolder(id)` helper when semantics match exactly.
+
+## RF-SLIDE-STATEMENTS — Slide Statements
+
+### Intent
+Reorder statements so related code is adjacent and a later extraction or simplification becomes possible.
+
+### Typical Signals
+- Statements that belong together are separated by unrelated work.
+
+### Avoid When
+- Do not reorder across side effects, awaits, exceptions, subscriptions, or reads/writes whose order is observable.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Map dependencies and side effects between statements.
+2. Move the smallest statement across only independent operations.
+3. Verify after each move.
+4. Stop when the intended cluster is adjacent.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-DUPLICATED-CODE`
+- `SMELL-MUTABLE-DATA`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: two normalization statements are separated by an unrelated analytics call. After: move only if analytics timing and data dependencies are unchanged.
+
+## RF-SPLIT-LOOP — Split Loop
+
+### Intent
+Separate a loop that performs multiple independent tasks into focused passes.
+
+### Typical Signals
+- One loop computes unrelated results with separate accumulators.
+
+### Avoid When
+- Avoid when the extra pass is materially expensive or iteration order/side effects couple the tasks.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify independent loop responsibilities.
+2. Duplicate the iteration and keep one responsibility in each pass.
+3. Verify outputs/order/performance.
+4. Then extract or pipeline individual loops if useful.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LONG-FUNCTION`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: one loop both counts unread messages and builds attachment names. After: split into two focused passes when collection size and order permit.
+
+## RF-REPLACE-LOOP-WITH-PIPELINE — Replace Loop with Pipeline
+
+### Intent
+Express a collection transformation as a sequence of named filter/map/reduce-style operations.
+
+### Typical Signals
+- An imperative loop mostly filters, maps, or accumulates data and bookkeeping hides intent.
+
+### Avoid When
+- Keep loops for early exits, complex mutation, tight performance constraints, or async sequencing when clearer.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the element-level transformation stages.
+2. Replace one stage with an equivalent collection operation.
+3. Preserve ordering and callback semantics.
+4. Verify empty inputs, errors, and performance-sensitive paths.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LOOPS`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: push matching attachment names into an array inside a loop. After: `attachments.filter(isVisible).map(a => a.name)` when behavior matches.
+
+## RF-REMOVE-DEAD-CODE — Remove Dead Code
+
+### Intent
+Remove code proven to have no reachable runtime or supported-tooling use.
+
+### Typical Signals
+- A function, export, branch, asset, style, route, or dependency has no legitimate references.
+
+### Avoid When
+- Do not infer deadness from grep alone when dynamic imports, routes, Storybook, i18n, Tailwind classes, runtime templates, or external consumers may reference it.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Prove unused status across static and dynamic reference channels.
+2. Classify risk before deletion.
+3. Use the dedicated cleanup workflow for actual removal.
+4. Run relevant build/tests after deletion.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-SPECULATIVE-GENERALITY`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Module initialization order, circular imports, closures, and dynamic imports can make a textual move behavior-changing.
+
+### TypeScript Notes
+- Preserve exported types, path aliases, package boundaries, and type-only/runtime import distinctions.
+
+### React Notes
+- Check Hook rules, Server/Client boundaries, lazy components, Suspense, router behavior, and event ordering when moving code.
+
+### Vue Notes
+- Check composable lifecycle, Pinia ownership, async setup, route guards, and auto-import conventions.
+
+### Frontend-Craft Adaptation
+- Place behavior with the data/change responsibility it serves, not merely in a “utilities” folder; prove dead code with the specialized cleanup lane.
+
+### Example Transformation
+Before: an obsolete component appears unused. After: route actual proof and deletion through `fec-refactor-clean`, including dynamic-reference checks.

package/skills/fec-refactoring-validation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fec-refactoring-validation
+description: Use when proving that a frontend refactoring preserved existing behavior, selecting an appropriate safety net, validating each structural step, or assigning a PASS, PARTIAL, or NOT PROVEN preservation verdict.
+---
+
+# Skill: Refactoring Validation
+
+## Purpose
+
+Define the observable contract and the smallest credible evidence needed to prove that structural edits preserved existing frontend behavior.
+
+## Procedure
+
+1. Record the relevant behavior contract before substantial edits.
+2. Classify safety-net coverage as A, B, or C.
+3. Run and record the pre-change baseline.
+4. Match verification to the current refactoring risk and affected boundary.
+5. After every structural step, run the narrowest sufficient check immediately.
+6. If a newly introduced failure appears, revert that step before broader repair.
+7. At the end, run the broad gates justified by the affected surface.
+8. Assign PASS, PARTIAL, or NOT PROVEN from evidence, not optimism.
+
+Pure structural work uses **GREEN → REFACTOR → GREEN**.
+
+## Safety-Net Levels
+
+| Level | Evidence | Execution guidance |
+| --- | --- | --- |
+| A — Strong | Existing tests cover relevant behavior | Use tests as the primary safety net |
+| B — Partial | Important behavior is only partly covered | Add focused characterization of current behavior before risky steps |
+| C — None | No useful automated behavior coverage | Do not auto-install a framework; keep CAUTION/DANGER plan-only unless a minimal safety net is authorized |
+
+## Frontend Contract Checklist
+
+Check relevant items, not every item mechanically:
+
+- function inputs, outputs, exceptions, and error mapping;
+- DOM structure that consumers depend on, visible states, focus, keyboard flow, and accessibility semantics;
+- props, emits, slots, hook/composable return values, and event ordering;
+- requests, payloads, cancellation, retries, cache keys, and loading/error transitions;
+- store state, persistence, object identity, memoization, refs/reactivity, and lifecycle timing;
+- routes, URLs, guards, package exports, serialized fields, and backend-facing DTOs.
+
+## References
+
+- Load [behavior-preservation.md](references/behavior-preservation.md) for contract construction and proof levels.
+- Load [refactoring-test-checklist.md](references/refactoring-test-checklist.md) for targeted verification by frontend risk.
+
+## Constraints
+
+- Passing unrelated tests does not prove preservation.
+- A green test written only after the change is weaker evidence than a pre-change baseline or characterization test.
+- Do not rewrite expected values simply because the refactor changed behavior.
+- Do not hide missing proof behind a PASS label.
+- Do not install a new test framework without explicit authorization.
+
+## Expected Output
+
+A behavior-preservation record containing baseline status, safety-net level, per-step checks, final validation, unresolved coverage gaps, and a PASS/PARTIAL/NOT PROVEN verdict.

package/skills/fec-refactoring-validation/references/behavior-preservation.md

@@ -0,0 +1,53 @@
+# Behavior Preservation
+
+## Build the Contract
+
+Before changing structure, identify which observations must remain stable. Use the smallest contract that fully covers the affected boundary.
+
+### Functional contract
+
+- accepted inputs and normalization;
+- return values and output ordering;
+- errors, exceptions, and fallback behavior;
+- side effects and significant ordering.
+
+### UI contract
+
+- rendered states and user-visible text/data;
+- enabled/disabled behavior;
+- focus and keyboard transitions;
+- event/callback ordering;
+- accessibility relationships that users or tests rely on.
+
+### State and async contract
+
+- store transitions and persistence;
+- request count, URL, method, payload, cancellation, retry, and error mapping;
+- loading/error/empty state timing;
+- React identity/memoization and hook dependency semantics;
+- Vue `ref`, `reactive`, `computed`, `watch`, and lifecycle identity/timing.
+
+### Public contract
+
+- exported symbols and call signatures;
+- routes and URL parameters;
+- serialized fields and API DTOs;
+- extension, plugin, template, or runtime registration points.
+
+## Characterization Tests
+
+When behavior is important but weakly covered, write a narrow test that captures current behavior before a risky structural edit. It may pass immediately because it records the existing contract. Do not broaden it into a new requirement.
+
+## Verdicts
+
+### PASS
+
+Use only when the relevant contract is well identified, the before/after baseline is comparable, and all required checks pass.
+
+### PARTIAL
+
+Use when checks pass but meaningful paths remain untested or only static/manual evidence covers an important boundary.
+
+### NOT PROVEN
+
+Use when dependencies cannot be installed, required tools cannot run, the baseline is ambiguous, or the safety net cannot credibly distinguish preservation from accidental behavior change.

package/skills/fec-refactoring-validation/references/refactoring-test-checklist.md

@@ -0,0 +1,42 @@
+# Refactoring Test Checklist
+
+## Local Function or Module
+
+- targeted unit tests for inputs, outputs, and errors;
+- typecheck of affected package/module;
+- callers compile with unchanged contracts;
+- no public export change unless planned.
+
+## React
+
+- hook order and dependency arrays remain valid;
+- stale closure behavior is not introduced;
+- controlled/uncontrolled ownership remains stable;
+- memoization or referential equality assumptions are preserved;
+- effect cleanup, request cancellation, and event order remain stable;
+- Server/Client boundaries and hydration behavior are unchanged when relevant.
+
+## Vue
+
+- `ref`/`reactive` identity and unwrapping semantics remain stable;
+- computed values stay derived rather than duplicated mutable state;
+- watchers keep intended source, flush timing, and cleanup;
+- props, emits, slots, and expose contracts remain stable;
+- Pinia store ownership and persistence remain stable.
+
+## API and Data
+
+- request shape, headers, auth refresh, cancellation, retry, and errors remain stable;
+- field renames do not cross DTO, storage, query-string, or backend contracts unintentionally;
+- sorting/filtering transformations preserve order, duplicates, and edge cases;
+- reference-to-value or value-to-reference changes preserve required identity semantics.
+
+## Routing and Runtime Registration
+
+- route names/paths/guards remain stable;
+- dynamic imports and lazy registrations remain discoverable;
+- Storybook, i18n, CSS/Tailwind dynamic classes, runtime templates, and generated metadata are not broken by search-only reasoning.
+
+## Final Ladder
+
+Run available checks from narrowest to broadest: targeted tests -> affected integration tests -> lint/typecheck -> full tests -> build -> E2E/SSR/visual/a11y/performance specialty gates when the refactoring touches those risks.

package/skills/fec-security-review/SKILL.md

@@ -5,6 +5,22 @@ description: Use when reviewing frontend security risks such as XSS, CSRF, sensi
 
 # Front-end security review
 
+## Review modes and coverage
+
+User-specified scope takes precedence over the default. Use the following three review modes:
+
+- **Change review**: only when recent changes, current edits, staged changes, a PR or a commit are explicitly requested or clearly established by the active task, review those changes and necessary context. For local changes, inspect staged and unstaged diffs and relevant untracked project files within the requested scope; a staged-only request reviews only staged changes. If there are no changes, report that there is nothing to review; do not switch to recent commits or expand scope automatically.
+- **Targeted review**: when files or directories are specified, inventory and review existing code in that scope, including unchanged code; no Git diff is required.
+- **Project review (default)**: when no scope or change context is specified, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review in module batches, including unchanged code; no Git diff is required.
+
+Select scope before collecting diffs. A file/directory alone means full review of that scope; a path combined with an explicit change request restricts incremental review to that path. An unqualified invocation defaults to project review even if Git changes exist. At review start, state the selected mode and target scope. When automatically delegating review after edits, pass the current change scope explicitly; do not trigger project review merely because the reviewer was called.
+
+Exclude dependency directories, build outputs, caches, generated files and third-party code by default, and record exclusions. Keep the frontend responsibility boundary; this is not a backend audit. A nonexistent target or a scope with no relevant files must be reported explicitly, not replaced with another scope.
+
+Merge findings with the same root cause across batches. Report **review mode, target scope, reviewed files/modules, exclusions, unreviewed files/modules, completion status and verification commands/results**. If context or execution limits prevent completion, mark the review partial and list remaining modules; never claim complete project coverage. Reading callers for context or running project-wide lint/typecheck does not count as manual review of those files.
+
+Change reviews retain merge recommendations. Targeted and project reviews use a risk assessment (Low / Medium / High, with blocking findings), not a claim of merge readiness. Preserve severity levels, evidence requirements and report filenames. Output reports only unless repairs are explicitly requested.
+
 ## Purpose
 
 Identify client-side security risks in front-end code and recommend actionable fixes.
@@ -36,3 +52,7 @@ Identify client-side security risks in front-end code and recommend actionable f
 ## Expected Output
 
 Output a CRITICAL/HIGH/MEDIUM/LOW graded security review report. Each issue is associated with a specific file and line number, and repair suggestions are given; the report is saved as `reports/security-review-YYYY-MM-DD-HHmmss.md`.
+
+## Engineering practices
+
+Read the [local engineering decisions](references/engineering-practices.md) for this task and follow their links to relevant shared principles. Apply levels and exceptions against actual project contracts; product frontend/backend labels do not constrain language or role.