@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/skills/fec-refactoring/references/principles.md

@@ -1,60 +1,13 @@
-# Refactoring Principles
+# Frontend refactoring contracts
 
-## Definition
+Shared behavior preservation, baseline, risk and diff-budget rules live in the [common method](common/refactoring.md).
 
-Refactoring changes the internal organization of existing code without intentionally changing its observable behavior. The purpose is to make future change safer and easier, not to smuggle new behavior into a structural patch.
+Additional frontend evidence covers:
 
-## Eight Hard Rules
+- Props, emits, slots, hooks/composables, identity and lifecycle.
+- DOM, loading/error/empty states, focus, keyboard and accessibility.
+- Routes, URLs, lazy loading, SSR/hydration and dynamic registration.
+- Requests, authentication, cancellation, retries, cache keys, optimistic updates and state ownership.
+- Exports, i18n keys, Storybook, generated templates and dynamic Tailwind classes.
 
-1. **Behavior Preservation:** define the relevant observable contract before substantial edits.
-2. **Green Baseline First:** distinguish pre-existing failures from regressions introduced by the current step.
-3. **One Refactoring at a Time:** keep each step attributable to one structural intent.
-4. **Verify Every Step:** use feedback at the smallest useful scope before continuing.
-5. **Revert Before Repairing:** a new regression invalidates the current step; restore the previous state before redesigning it.
-6. **Separate Feature Work:** new outcomes, changed rules, or changed error behavior are not pure refactoring.
-7. **Smallest Safe Refactoring First:** prefer a reversible local change over a speculative redesign.
-8. **Stay Within the Diff Budget:** scope growth is a stop signal, not permission to keep expanding.
-
-## Observable Behavior
-
-Depending on the code, preservation can include:
-
-- return values, thrown errors, and error mapping;
-- side effects and their ordering when order is semantically significant;
-- requests, payloads, retries, cancellation, and authentication behavior;
-- state transitions, persistence, cache identity, and memoization-sensitive object identity;
-- rendered DOM, loading/error/empty states, focus, keyboard behavior, and emitted events;
-- props, emits, slots, hook/composable contracts, package exports, routes, and URLs.
-
-## Evidence Model
-
-Use concrete evidence before choosing a technique:
-
-- call sites and dependency direction;
-- ownership of the data being read or mutated;
-- change history or repeated edit locations when available;
-- tests and documented public contracts;
-- runtime registration points, dynamic imports, route tables, i18n keys, Storybook stories, and generated templates;
-- framework lifecycle semantics and state identity.
-
-Metrics may indicate where to look, but they do not independently prove the diagnosis.
-
-## Risk Model
-
-### SAFE
-
-Local/private scope, no public contract, no subtle lifecycle or persistence semantics, strong rollback path, and relevant verification available.
-
-### CAUTION
-
-Cross-file or cross-component restructuring, shared helpers, state ownership changes, lifecycle-sensitive code, dynamic references, or incomplete behavioral coverage.
-
-### DANGER
-
-Public APIs, routes, storage schemas, backend contracts, authentication or permissions, SSR/hydration, critical calculations, broad inheritance replacement, or architecture-wide state movement.
-
-Do not assign permanent risk to a catalog technique. The same rename can be SAFE for a local variable and DANGER for a serialized field.
-
-## Characterization Before Risky Change
-
-When important current behavior is not directly tested, add characterization coverage that describes what the code already does. Such a test can start green; its purpose is to lock existing behavior, not to invent a new requirement.
+Use callers, dependency direction, data ownership and actual verification as evidence; line count alone does not establish a structural problem.

package/skills/fec-refactoring/references/workflow.md

@@ -1,90 +1,7 @@
-# Refactoring Workflow
+# Frontend refactoring validation
 
-## State Machine
+Execution order, rollback and proof verdicts follow the [common method](common/refactoring.md).
 
-```text
-CLASSIFY REQUEST
-  -> DISCOVER CONTEXT
-  -> ESTABLISH BASELINE
-  -> DIAGNOSE STRUCTURAL EVIDENCE
-  -> ESTABLISH SAFETY
-  -> BUILD ORDERED PLAN
-  -> RISK CHECK
-  -> EXECUTE ONE STEP
-  -> VERIFY STEP
-       PASS -> inspect diff -> next step
-       FAIL -> revert current step -> confirm baseline -> shrink/replan
-  -> FINAL VALIDATION
-  -> REPORT
-```
+Choose checks by risk: nearest types/static checks → utilities/hooks/components → Router/Provider/Store integration → full lint/types/tests → build and affected SSR, E2E, accessibility, visual or performance checks.
 
-## Context Discovery
-
-Read only what is needed to establish facts:
-
-- `package.json`, workspace manifests, TypeScript and lint configuration;
-- test configuration and scripts;
-- affected modules, callers, imports, barrel exports, routes, and registration points;
-- state/store ownership and persistence boundaries;
-- framework conventions, lifecycle-sensitive code, async effects, and current Git diff.
-
-## Baseline Handling
-
-If the baseline is green, any newly failing relevant check after a step is presumptive evidence that the step regressed behavior or structure.
-
-If the baseline is already red:
-
-1. record exact failing commands and symptoms;
-2. do not claim later failures are caused by refactoring without comparison evidence;
-3. avoid risky restructuring unless the preserved contract remains credible;
-4. separate unexplained failure diagnosis from structural change.
-
-## Plan Step Contract
-
-Each executable step records:
-
-```text
-Target:
-Technique:
-Intent:
-Prerequisites:
-Risk: SAFE | CAUTION | DANGER
-Expected files:
-Expected functions/components:
-Expected public API changes: 0
-Expected behavior changes: 0
-Verification:
-Rollback boundary:
-```
-
-Order prerequisites before larger moves. For example, expose a stable query before extracting logic that depends on it, or isolate a conditional before replacing its dispatch mechanism.
-
-## Step Failure Protocol
-
-When a previously green check becomes red:
-
-1. stop;
-2. revert only the current structural step;
-3. rerun the affected check to confirm restoration;
-4. identify whether the failed assumption was behavior, identity, lifecycle, ordering, typing, or dependency related;
-5. shrink the step or add a safer prerequisite;
-6. retry only after the plan is again evidence-backed.
-
-Do not spread fixes across unrelated modules merely to make the suite green.
-
-## Final Validation
-
-Use a narrow-to-broad ladder:
-
-1. nearest syntax/type/static check;
-2. targeted unit or component tests;
-3. affected package or integration tests;
-4. lint and full typecheck;
-5. broader test suite;
-6. build, SSR, E2E, visual, accessibility, performance, or specialty checks when affected.
-
-## Proof Verdict
-
-- **PASS:** the relevant observable contract is adequately covered and required checks pass.
-- **PARTIAL:** executed checks pass, but important behavior remains incompletely covered.
-- **NOT PROVEN:** missing dependencies, environment limits, baseline failures, or insufficient safety evidence prevent a credible preservation claim.
+Record actual project commands, UI/state/network observations, baseline failures, per-step changes and rollback boundaries. Pure structural refactoring does not invent new behavioral failures or revert unrelated user work.

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

@@ -52,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.

package/skills/fec-security-review/references/common/engineering-practices.md

@@ -0,0 +1,237 @@
+# Engineering practices
+
+Read project contracts first, then only the relevant core sections and local language/scenario cards. These are project-native decisions informed by the linked primary sources, not certification by those organizations. `required` protects stated correctness/safety contracts; `recommended` is a default with reasoned alternatives; `conditional` activates only when its stated predicate holds. Project safety/compatibility and actual toolchain facts take priority over corporate style.
+
+<a id="ENG-CONTRACT"></a>
+## ENG-CONTRACT — Contracts before representation
+
+Level: required
+
+### Risk
+An accepted input can still violate the caller’s operation or output contract.
+
+### Applies
+Applies at public APIs, files, IPC and serialized input. Internal trusted values can rely on a proven invariant; rechecking everything is not the goal.
+
+### Decision
+Name the caller, accepted values, units, failure/output state and compatibility promise. Validate unknown data once at the boundary before effects; keep protocol mapping outside pure domain logic.
+
+### Exceptions
+If a trusted upstream validator owns the invariant, record its scope instead of adding a second schema. Type assertions and generated types alone provide no runtime guarantee.
+
+### Examples
+Better: reject a malformed amount before charging. Worse: cast JSON and let a partial effect reveal invalid input.
+
+### Verification
+Check invalid, boundary and successful inputs, plus effects/output state; exercise a real packed consumer when shipping a package.
+
+### Sources
+- [Publishing declaration files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) (typescript-publishing)
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) (rust-api)
+
+Case evidence IDs: EP-TS-01, EP-SVC-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-ERROR"></a>
+## ENG-ERROR — Observable failure
+
+Level: required
+
+### Risk
+A fallback can erase the cause or report success after partial work.
+
+### Applies
+Applies when a failure crosses an abstraction or process boundary. Expected absence may use an explicit optional result rather than an exception.
+
+### Decision
+Preserve the cause and operation context, return a typed/declared failure, and let the owning boundary choose recovery. Cleanup failure must not silently replace the primary failure.
+
+### Exceptions
+Translate sensitive internal details into a safe public error while preserving a correlation path in permitted diagnostics. Do not log credentials or raw private payloads.
+
+### Examples
+Better: failure plus original cause and released owned resources. Worse: catch everything and return an empty successful object.
+
+### Verification
+Inject a downstream failure; assert the caller observes failure, its cause and the agreed cleanup outcome.
+
+### Sources
+- [Try-with-resources](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) (oracle-resources)
+- [Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md) (uber-go)
+
+Case evidence IDs: EP-RS-01, EP-JAVA-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-RESOURCE"></a>
+## ENG-RESOURCE — Own the full lifecycle
+
+Level: required
+
+### Risk
+Partial acquisition, borrowed handles and teardown create leaks or double release.
+
+### Applies
+Applies when code acquires files, allocations, tasks, subscriptions or external handles. Pure value transformations need no invented resource manager.
+
+### Decision
+Identify acquire/use/transfer/release owners. Release acquired resources on every exit, in dependency order; borrowed values stay with their owner. Importing a library should not acquire unrelated external resources.
+
+### Exceptions
+A documented transfer or process-lifetime resource needs an explicit recipient or lifetime contract. Finalizers and process exit alone do not prove orderly shutdown.
+
+### Examples
+Better: fail the second allocation and release only the first owned allocation. Worse: free the caller’s borrowed buffer.
+
+### Verification
+Count acquisitions/releases under each failure point and successful transfer. Record untested drivers, GUI shutdown and sanitizer coverage separately.
+
+### Sources
+- [MEM00-C allocation and release](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/) (cert-c)
+- [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) (cpp-core)
+
+Case evidence IDs: EP-C-01, EP-CPP-01, EP-PY-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-CONCURRENCY"></a>
+## ENG-CONCURRENCY — Cancellation and completion differ
+
+Level: conditional
+
+### Risk
+Detached work can outlive owners; an old result may overwrite current state.
+
+### Applies
+Applies if the unit starts concurrent work or receives asynchronous results. Sequential pure code need not gain a scheduler.
+
+### Decision
+Keep completion handles, cancellation ownership and bounded in-flight work. Stop accepting work, request cancellation/drain, then observe termination. Check request identity/liveness before publishing results.
+
+### Exceptions
+Some blocking operations ignore cancellation; expose incomplete shutdown or a caller-owned forced-exit policy. Arc, channel capacity and an abort request are not completion evidence.
+
+### Examples
+Better: controlled B-before-A responses keep B visible. Worse: a timed-out caller frees resources while workers still use them.
+
+### Verification
+Use barriers/events and controlled futures for cancellation, saturation and late results; arbitrary sleeps are not ordering proof.
+
+### Sources
+- [context package](https://pkg.go.dev/context) (go-context)
+- [JoinHandle](https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html) (tokio-join)
+- [Coroutines and tasks](https://docs.python.org/3/library/asyncio-task.html) (python-asyncio)
+
+Case evidence IDs: EP-GO-01, EP-IPC-01, EP-UI-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-BOUNDARY"></a>
+## ENG-BOUNDARY — Trust is established at an actual boundary
+
+Level: required
+
+### Risk
+A frontend/backend label can hide privileged operations or untrusted callers.
+
+### Applies
+Applies to external input, authorization and privilege changes across UI, IPC, library and service roles. A private pure helper is not a new authentication layer.
+
+### Decision
+Verify sender/identity through the actual trusted mechanism, validate operation-specific data and scope permissions. A renderer-provided role or hidden button is not authority.
+
+### Exceptions
+Offline/local-only tools still have a caller and data boundary. Do not add network authentication where the contract needs only a constrained local capability.
+
+### Examples
+Better: expose one validated IPC operation with sender checks. Worse: expose arbitrary filesystem methods to a renderer.
+
+### Verification
+Exercise denied and allowed calls and zero effects after rejection. Native permission activation/signing needs its own actual environment evidence.
+
+### Sources
+- [Security](https://www.electronjs.org/docs/latest/tutorial/security) (electron-security)
+- [Permissions](https://v2.tauri.app/security/permissions/) (tauri-permissions)
+
+Case evidence IDs: EP-TS-01, EP-IPC-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-DEPENDENCY"></a>
+## ENG-DEPENDENCY — Ship a usable consumer contract
+
+Level: recommended
+
+### Risk
+Working inside a repository can conceal undeclared dependencies or incompatible artifacts.
+
+### Applies
+Applies when publishing, upgrading dependencies or changing exported APIs. A content-only note does not require changing every tool version.
+
+### Decision
+Read manifests, locks, supported targets and exports first. Keep dependencies explicit, changes scoped and migration reversible; validate the artifact from an independent consumer.
+
+### Exceptions
+Adopt a dependency or compiler change only for an evidenced need and compatible policy. A corporate guide’s preferred build system is not such evidence.
+
+### Examples
+Better: declarations resolve with the packed files and declared dependencies. Worse: publish types that only resolve through adjacent source aliases.
+
+### Verification
+Inspect real archive bytes, install away from sibling sources and run supported consumer checks; record the exact version/integrity and untested platforms.
+
+### Sources
+- [Publishing declaration files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) (typescript-publishing)
+- [Code review standard](https://google.github.io/eng-practices/review/reviewer/standard.html) (google-review)
+
+Case evidence IDs: EP-TS-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-VERIFICATION"></a>
+## ENG-VERIFICATION — Evidence matches the claimed behavior
+
+Level: required
+
+### Risk
+A green structural check or missing tool can be mistaken for behavioral proof.
+
+### Applies
+Applies to implementation, review and delivery claims. Read-only advice can state proposed checks without pretending execution.
+
+### Decision
+Choose tests by risk and observable boundaries. Separate environment preparation from execution; keep fixed assertions for faulty/fixed variants and report actual commands, counts and limitations.
+
+### Exceptions
+When tools are absent, report MISSING; when intentionally unexecuted, NOT RUN. Compile errors and zero/all-skipped suites do not prove business RED/GREEN.
+
+### Examples
+Better: failure injection breaks a named effect assertion, then the fixed version passes it. Worse: only grep for a PASS string.
+
+### Verification
+Retain raw output, input/tool hashes and scope. Structure, native behavior and model-task decisions are distinct evidence.
+
+### Sources
+- [Test planning](https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/) (ms-playbook)
+- [Fault injection testing](https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/) (ms-faults)
+- [Code review standard](https://google.github.io/eng-practices/review/reviewer/standard.html) (google-review)
+
+Case evidence IDs: EP-TS-01, EP-C-01, EP-SVC-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.
+
+<a id="ENG-OPERABILITY"></a>
+## ENG-OPERABILITY — Make recovery explicit and bounded
+
+Level: conditional
+
+### Risk
+Partial failure, retry amplification and unsafe diagnostics can worsen an incident.
+
+### Applies
+Applies where this unit owns an external operation, background lifecycle or recovery decision. Libraries should expose signals, not force service dashboards or HTTP layers.
+
+### Decision
+Classify failure and commit uncertainty; make operation intent, total timeout/retry budget and recovery owner explicit. Use a stable idempotency contract for writes before replay. Emit safe correlation and actionable failure state.
+
+### Exceptions
+Without server-side safety, leave a write pending confirmation and offer reconciliation. A timeout/cancel is not proof that no effect occurred; 429/5xx alone do not authorize replay.
+
+### Examples
+Better: repeat the same key/intent and reuse the committed result. Worse: generate a new key after a payment timeout.
+
+### Verification
+Inject failure after commit but before response, replay concurrently and reject a changed intent; separate process-local tests from database or distributed guarantees.
+
+### Sources
+- [Timeouts, retries and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) (aws-retry)
+- [Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/) (aws-idempotency)
+
+Case evidence IDs: EP-SVC-01, EP-UI-01. Identifiers are not cross-entry file dependencies; consult local examples and the coverage report for execution status.

package/skills/fec-security-review/references/common/engineering-practices.rules.json

@@ -0,0 +1,121 @@
+{
+  "schemaVersion": 1,
+  "rules": [
+    {
+      "id": "ENG-CONTRACT",
+      "kind": "core",
+      "level": "required",
+      "anchor": "ENG-CONTRACT",
+      "sourceIds": [
+        "typescript-publishing",
+        "rust-api"
+      ],
+      "caseIds": [
+        "EP-TS-01",
+        "EP-SVC-01"
+      ]
+    },
+    {
+      "id": "ENG-ERROR",
+      "kind": "core",
+      "level": "required",
+      "anchor": "ENG-ERROR",
+      "sourceIds": [
+        "oracle-resources",
+        "uber-go"
+      ],
+      "caseIds": [
+        "EP-RS-01",
+        "EP-JAVA-01"
+      ]
+    },
+    {
+      "id": "ENG-RESOURCE",
+      "kind": "core",
+      "level": "required",
+      "anchor": "ENG-RESOURCE",
+      "sourceIds": [
+        "cert-c",
+        "cpp-core"
+      ],
+      "caseIds": [
+        "EP-C-01",
+        "EP-CPP-01",
+        "EP-PY-01"
+      ]
+    },
+    {
+      "id": "ENG-CONCURRENCY",
+      "kind": "core",
+      "level": "conditional",
+      "anchor": "ENG-CONCURRENCY",
+      "sourceIds": [
+        "go-context",
+        "tokio-join",
+        "python-asyncio"
+      ],
+      "caseIds": [
+        "EP-GO-01",
+        "EP-IPC-01",
+        "EP-UI-01"
+      ]
+    },
+    {
+      "id": "ENG-BOUNDARY",
+      "kind": "core",
+      "level": "required",
+      "anchor": "ENG-BOUNDARY",
+      "sourceIds": [
+        "electron-security",
+        "tauri-permissions"
+      ],
+      "caseIds": [
+        "EP-TS-01",
+        "EP-IPC-01"
+      ]
+    },
+    {
+      "id": "ENG-DEPENDENCY",
+      "kind": "core",
+      "level": "recommended",
+      "anchor": "ENG-DEPENDENCY",
+      "sourceIds": [
+        "typescript-publishing",
+        "google-review"
+      ],
+      "caseIds": [
+        "EP-TS-01"
+      ]
+    },
+    {
+      "id": "ENG-VERIFICATION",
+      "kind": "core",
+      "level": "required",
+      "anchor": "ENG-VERIFICATION",
+      "sourceIds": [
+        "ms-playbook",
+        "ms-faults",
+        "google-review"
+      ],
+      "caseIds": [
+        "EP-TS-01",
+        "EP-C-01",
+        "EP-SVC-01"
+      ]
+    },
+    {
+      "id": "ENG-OPERABILITY",
+      "kind": "core",
+      "level": "conditional",
+      "anchor": "ENG-OPERABILITY",
+      "sourceIds": [
+        "aws-retry",
+        "aws-idempotency"
+      ],
+      "caseIds": [
+        "EP-SVC-01",
+        "EP-UI-01"
+      ]
+    }
+  ]
+}