@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/skills/fec-react-project-standard/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/skills/fec-react-project-standard/references/engineering-practices.md

@@ -0,0 +1,73 @@
+---
+practiceCards:
+  - id: "fec-react-project-standard:effect-cleanup"
+    level: "required"
+    sourceIds: ["react-effects","react-act"]
+    caseIds: ["EP-UI-01"]
+    evidence: "case"
+  - id: "fec-react-project-standard:stale-results"
+    level: "conditional"
+    sourceIds: ["react-effects","react-act"]
+    caseIds: ["EP-UI-01"]
+    evidence: "case"
+---
+
+# Local engineering decisions
+
+Locate the actual role, toolchain and existing conventions, then read relevant [shared principles](common/engineering-practices.md). These conditions apply to this entry, not every project. Structure checks do not prove all semantics or execution.
+
+<a id="fec-react-project-standard:effect-cleanup"></a>
+## Effects release the resources they actually own
+
+Level: required
+
+### Risk
+A removed component can leave requests, listeners or timers active.
+
+### Applies
+When the component itself starts an effect. Shared cache/client work retains its own owner; unsubscription is not authority to cancel every consumer.
+
+### Decision
+Pair setup with cleanup, forward cancellation to owned work, and make cleanup repeatable. Use actual installed React APIs and the existing component/query boundary.
+
+### Exceptions
+A development setup/cleanup cycle is not automatically a production bug. Abort indicates lost interest and cannot undo a committed server write.
+
+### Examples
+Better: cleanup aborts this component’s load and removes its listener. Worse: unmount clears a global client still used elsewhere.
+
+### Verification
+Run the local real React/DOM unmount test; add actual subscriptions/timers and Strict Mode behavior where the changed component owns them.
+
+### Sources
+react-effects, react-act — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-UI-01; case. [Local runnable example](../examples/engineering/README.md). Execution status and scope require actual records; a related ID does not prove every decision on this card.
+
+<a id="fec-react-project-standard:stale-results"></a>
+## Only the current view request may publish its result
+
+Level: conditional
+
+### Risk
+A late A success, error or finally can replace B’s current view state.
+
+### Applies
+For latest-result views; queued commands with independent outcomes require their own intent contract.
+
+### Decision
+Scope request identity/liveness to the owning view or query key and guard every state publication, including errors/loading. Cancellation and identity checks are complementary.
+
+### Exceptions
+Do not implement a global counter that invalidates unrelated components. Cancelling a submitted mutation does not establish rollback or permission to replay it.
+
+### Examples
+Better: B remains visible after A arrives late. Worse: only the success handler is guarded while old finally clears B’s loading state.
+
+### Verification
+The local controlled A/B Promise test renders real React. Add late-error/loading and shared-cache cases in the actual owner; DOM simulation is not browser E2E.
+
+### Sources
+react-effects, react-act — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-UI-01; case. [Local runnable example](../examples/engineering/README.md). Execution status and scope require actual records; a related ID does not prove every decision on this card.

package/skills/fec-react-project-standard/references/generic-component-types.md

@@ -0,0 +1,37 @@
+## Safer generic component pattern
+
+```tsx
+interface Entity {
+  id: string;
+}
+
+interface EntityPickerProps<TEntity extends Entity> {
+  items: TEntity[];
+  selectedId: string | null;
+  getLabel: (item: TEntity) => string;
+  onSelect: (item: TEntity) => void;
+}
+
+export function EntityPicker<TEntity extends Entity>({
+  items,
+  selectedId,
+  getLabel,
+  onSelect,
+}: EntityPickerProps<TEntity>) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>
+          <button
+            aria-pressed={item.id === selectedId}
+            type="button"
+            onClick={() => onSelect(item)}
+          >
+            {getLabel(item)}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```

package/skills/fec-react-project-standard/references/react-quality-patterns.md

@@ -27,9 +27,9 @@ Please note when adapting:
 
 ## TypeScript Specification
 
-Common TypeScript project rules are taken care of by `fec-typescript-project-standard`, including `tsconfig`, strictness, DTO / view model boundaries, `unknown` narrowing, public API types, declared artifacts, and type tests.
+Common TypeScript project rules are taken care of by `cc-typescript-project-standard`, including `tsconfig`, strictness, DTO / view model boundaries, `unknown` narrowing, public API types, declared artifacts, and type tests.
 
-The React specification only supplements components, Props, events and TSX generic writing; complex type modeling or cross-framework type contracts are first offloaded to `fec-typescript-project-standard`.
+The React specification only supplements components, Props, events and TSX generic writing; complex type modeling or cross-framework type contracts are first offloaded to `cc-typescript-project-standard`.
 
 ### React project supplementary conventions
 
@@ -119,7 +119,7 @@ When outputting React code or solutions, at least check:
 - [ ] Whether reusable logic has been extracted into hooks
 - [ ] loading / error / empty / data status is complete
 - [ ] Whether the API layer has type constraints and unified error handling
-- [ ] Whether complex DTO, external data narrowing, public types or `tsconfig` issues have been offloaded to `fec-typescript-project-standard`
+- [ ] Whether complex DTO, external data narrowing, public types or `tsconfig` issues have been offloaded to `cc-typescript-project-standard`
 - [ ] Whether status management complies with the proximity principle
 - [ ] Whether lazy loading is considered for routing-level or heavy-duty modules
 - [ ] Whether the style scheme is consistent with the warehouse

package/skills/fec-react-project-standard/references/react-runtime-patterns.md

@@ -28,7 +28,7 @@ The following patterns can be used in comparison with other chapters of this ski
 
 ### Form
 
-- Controlled fields + validation error objects are a feasible implementation; medium and large forms are given priority **React Hook Form** (or Formik) + **Zod**, and complex form values, DTO and validation type contracts are offloaded to `fec-typescript-project-standard`.
+- Controlled fields + validation error objects are a feasible implementation; medium and large forms are given priority **React Hook Form** (or Formik) + **Zod**, and complex form values, DTO and validation type contracts are offloaded to `cc-typescript-project-standard`.
 - Avoid huge `useState` form objects and repeated validation logic in a single component, detachable field subcomponents or extract `useFormSchema`.
 
 ### Error Boundary

package/skills/fec-refactoring/SKILL.md

@@ -3,81 +3,23 @@ name: fec-refactoring
 description: Use when restructuring existing frontend code while preserving observable behavior, including responsibility extraction, module movement, conditional simplification, API cleanup, or data organization. Do not use for new feature behavior, behavior-changing bug fixes, dependency or framework migrations, or proven dead-code cleanup.
 ---
 
-# Skill: Behavior-Preserving Refactoring
+# Frontend behavior-preserving refactoring
 
-## Purpose
+Follow the [common refactoring method](references/common/refactoring.md): GREEN → REFACTOR → GREEN. Its shared contract defines Behavior Preservation, Green Baseline First, One Refactoring at a Time, Verify Every Step, Revert Before Repairing, and the Diff Budget.
 
-Restructure live frontend code in small, evidence-backed steps while preserving the behavior users, callers, tests, routes, and integrations can observe.
+## Frontend observable boundaries
 
-## Core Contract
+Identify props/emits/slots, hooks/composables, DOM, loading/error/empty states, focus/keyboard behavior, routes/URLs, state ownership and object identity, requests, caches, lifecycles, SSR/hydration, exports and dynamic registration.
 
-Every execution follows these rules:
+## Frontend risk and scope
 
-1. **Behavior Preservation** — pure refactoring intentionally changes structure, not observable behavior.
-2. **Green Baseline First** — record available verification before editing.
-3. **One Refactoring at a Time** — one primary structural intent per step.
-4. **Verify Every Step** — run the narrowest meaningful check immediately after each step.
-5. **Revert Before Repairing** — if a new regression appears, revert that step before widening the edit.
-6. **Separate Refactoring from Feature Work** — behavior changes belong in a different workflow.
-7. **Smallest Safe Refactoring First** — prefer the narrowest transformation that fits the evidence.
-8. **Stay Within the Diff Budget** — stop when actual scope materially exceeds the planned scope.
+Assess authentication, permissions, routing, storage, SSR/hydration, network contracts and architecture-wide state movement by their actual effects. A technique name does not establish SAFE risk.
 
-Pure refactoring uses **GREEN → REFACTOR → GREEN**. Do not manufacture a failing behavioral test merely to make a structural change look like feature TDD.
+## Domain references
 
-## Procedure
+- [Domain evidence and observable contracts](references/principles.md)
+- [Frontend validation ladder](references/workflow.md)
+- [When to refactor](references/when-to-refactor.md)
+- [Boundary with behavior changes](references/refactoring-vs-feature-change.md)
 
-1. **Classify the request.** Confirm that the intended result is structural and behavior-preserving.
-2. **Discover context.** Read project configuration, affected modules, public exports, routes, state boundaries, tests, and current diff.
-3. **Record observable contracts.** Capture inputs, outputs, errors, side effects, UI states, events, network calls, state transitions, routes, and public APIs that matter.
-4. **Establish the baseline.** Run existing narrow checks first; record pre-existing failures rather than attributing them to later edits.
-5. **Diagnose structural evidence.** Identify the concrete smell or responsibility problem and check likely false positives.
-6. **Build the safety net.** Reuse relevant tests; add characterization coverage only when needed to preserve existing behavior.
-7. **Plan ordered micro-refactorings.** For each step record technique, rationale, prerequisites, risk, Diff Budget, verification, and rollback boundary.
-8. **Apply exactly one primary transformation.** Avoid opportunistic cleanup, formatting churn, or unrelated redesign.
-9. **Verify immediately.** Compare actual scope with the Diff Budget and run targeted checks.
-10. **Handle regression.** Revert the current step, confirm the prior baseline, shrink or reorder the transformation, then retry only with evidence.
-11. **Run broad final validation.** Escalate from targeted checks to typecheck, tests, build, E2E, accessibility, or specialty checks when relevant.
-12. **Report proof strength.** Use PASS, PARTIAL, or NOT PROVEN and state remaining risk.
-
-## Risk Classification
-
-| Risk | Typical scope | Default action |
-| --- | --- | --- |
-| `SAFE` | Local/private code, stable contracts, easy rollback | Execute with step-level verification |
-| `CAUTION` | Cross-module movement, shared state, imports, hooks/composables, lifecycle | Execute only with adequate safety evidence |
-| `DANGER` | Public API, routes, persistence, network contracts, auth, SSR/hydration, broad state or inheritance redesign | Plan and stop for explicit approval unless already authorized |
-
-Risk is contextual. A technique name alone never proves that a change is safe.
-
-## Diff Budget
-
-Before each executable step record:
-
-```text
-Expected files: N
-Expected functions/components: N
-Expected public API changes: 0
-Expected behavior changes: 0
-```
-
-If the actual diff materially exceeds that budget, stop and reassess instead of silently expanding into redesign.
-
-## References
-
-- Load [principles.md](references/principles.md) for the safety rules, evidence model, and risk language.
-- Load [workflow.md](references/workflow.md) for the state machine, baseline handling, rollback, and reporting contract.
-- Load [when-to-refactor.md](references/when-to-refactor.md) when deciding whether restructuring is timely or should be deferred.
-- Load [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md) when ownership overlaps feature work, debugging, cleanup, migration, or review.
-
-## Constraints
-
-- Do not alter tests merely to accept behavior changed by the refactoring.
-- Do not label auth, permission, routing, persistence, protocol, or public package changes `SAFE` without specific evidence.
-- Do not stack additional structural edits after a newly introduced failure.
-- Do not install a new test framework automatically when the project has none.
-- Do not treat line count, complexity metrics, comments, a switch, or chaining as sufficient proof of a code smell.
-- Do not perform remote Git writes by default.
-
-## Expected Output
-
-A small-step refactoring plan or implementation with explicit evidence, risk, Diff Budget, per-step verification, rollback history when applicable, and a final PASS/PARTIAL/NOT PROVEN behavior-preservation verdict.
+Deliver the common method's PASS, PARTIAL or NOT PROVEN verdict, per-step Diff Budget, executed verification and residual risk.

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

@@ -0,0 +1,16 @@
+# Behavior-preserving refactoring
+
+Refactoring changes internal organization while preserving the observable contract. Use GREEN → REFACTOR → GREEN; do not manufacture a failing behavioral requirement for a structural change.
+
+1. Classify whether this is structural work, a new behavior, a defect fix, or a dependency migration. Keep behavior changes in a separate workflow.
+2. Read affected implementation, callers, exports, registration, persistence and tests. Define observable results, errors, side effects and ordering, state transitions, public names and protocols before editing.
+3. Establish the green baseline or record existing failures. If a relevant behavior lacks coverage, add characterization tests that describe current behavior; these may start green.
+4. Diagnose structural evidence and check false positives. Line count and complexity metrics alone do not justify a rewrite. Prefer the smallest safe, reversible transformation.
+5. Plan prerequisite steps. Each records target, structural intent, technique, risk, expected files/functions, expected public API/behavior changes (zero for pure refactoring), verification and rollback boundary.
+6. Change one primary structural concern, then run the nearest meaningful check and inspect the diff. Stop and reassess if the actual scope exceeds the planned diff budget.
+7. A new regression invalidates the current step: restore only that step, verify the previous baseline and shrink or reorder the transformation before retrying. Do not revert unrelated user edits or spread repairs across unrelated modules.
+8. Broaden verification as the changed contract requires: local/static checks, unit/integration, full lint/types/tests, build and relevant specialty checks. Use existing project tools rather than impose a framework.
+
+Risk is contextual: SAFE for local/private changes with strong evidence; CAUTION for cross-module/shared-state/lifecycle changes; DANGER for public APIs, schemas, persistence, authentication, permission, protocols or architecture-wide changes. A technique name alone never makes a change safe.
+
+Deliver a proof verdict: PASS when the relevant behavior is adequately covered and checks pass; PARTIAL when checks pass but coverage has important gaps; NOT PROVEN when evidence or environment prevents a credible preservation claim. Include executed commands, rollback decisions and remaining risks.