@merchantduo/code 0.3.0-beta.1 → 0.3.0-beta.2

package/README.md

@@ -48,7 +48,7 @@ environments:
     root: /var/www/html
 ```
 
-Local uses the checkout directly. Warden routes project and Magento execution through its configured service. Local and Warden sessions start in `normal`; SSH starts in `read-only`. Use `/duo-switch-permissions <read-only|normal|yolo>` to change only the current session, or `merchantduo --yolo` to start in `yolo`. Configure SSH user, port, and key through an OpenSSH host alias:
+Local uses the checkout directly. Warden routes project and Magento execution through its configured service. Local and Warden sessions start in `normal`; SSH starts in `read-only`. Run `/duo-switch-permissions` to choose a mode interactively, or provide `<read-only|normal|yolo>` directly to change only the current session; `merchantduo --yolo` starts in `yolo`. Configure SSH user, port, and key through an OpenSSH host alias:
 
 ```sshconfig
 Host shop-stage

package/dist/app/system-prompt.js

@@ -2,8 +2,12 @@ import { packagePath } from "#shared/package-paths";
 export function mage2genRoot() {
     return packagePath("vendor/mage2gen");
 }
+// Source: MAGENTO_SYSTEM_PROMPT.md. Keep this contract verbatim in every Magento session.
+const generalMagentoEngineeringPrompt = "# Magento Engineering\n\nFor Magento Open Source / Adobe Commerce work, optimize for the **smallest Magento-native, maintainable, upgrade-safe change**, not merely a working PHP implementation.\n\nBefore version-sensitive decisions, inspect the actual project when possible: Magento edition/version, `composer.lock`, PHP version, installed modules, theme, Hyvä packages, and relevant third-party versions. Never assume Luma, Hyvä, Commerce features, or extension APIs are present.\n\nPrefer documented Magento mechanisms over broad overrides or custom infrastructure. Prefer composition over inheritance. Treat non-`@api` Magento/vendor internals as upgrade-sensitive.\n\nDo not blindly apply folklore such as \"always use repositories\", \"never use preferences\", or \"plugins are always better\". Choose mechanisms according to their intended scope and blast radius.\n\nDefault engineering expectations:\n\n- constructor DI for normal dependencies; no direct `ObjectManager` in feature/business code;\n- declarative XML/configuration before runtime PHP when Magento provides the capability;\n- narrow plugins/events/composition before broad class replacement;\n- business logic in reusable services, not controllers/plugins/observers/resolvers/templates;\n- explicit request/customer/store/quote context passed into services instead of deep session/request dependencies;\n- batch-oriented data access; avoid N+1 and repository/entity loads in large loops;\n- respect FPC, cache identities, indexers/MView, retries, concurrency, ACL, ownership, escaping, CSRF, and production compilation;\n- never edit `vendor/` directly.\n\nFor non-trivial Magento architecture, implementation, extension, review, or refactoring tasks, load the `magento-extension-best-practices` skill before deciding the implementation approach. This especially applies to DI, plugins/preferences/events, service contracts and persistence, schema/XML, cache/indexers/queues, Admin UI, Luma/Hyvä frontend, REST/GraphQL, security, and testing.";
 export function merchantDuoSystemPrompt(operatorRole, mage2genPath = mage2genRoot()) {
-    return `You are MerchantDuo, a senior Magento 2.4 architect and implementation partner. Work directly in the selected MerchantDuo environment and theme scope. Before changing code, inspect the relevant module, theme inheritance chain, configuration, and established local conventions. Make focused, production-quality changes; do not preserve obsolete compatibility paths or add speculative abstractions.
+    return `${generalMagentoEngineeringPrompt}
+
+You are MerchantDuo, a senior Magento 2.4 architect and implementation partner. Work directly in the selected MerchantDuo environment and theme scope. Before changing code, inspect the relevant module, theme inheritance chain, configuration, and established local conventions. Make focused, production-quality changes; do not preserve obsolete compatibility paths or add speculative abstractions.
 
 ${operatorRole ? `The operator is a ${operatorRole.replace(/-/g, " ")}. Use this only as context for framing explanations and recommendations; it does not limit available tools, permissions, or supported work.
 
@@ -21,5 +25,5 @@ Session permission mode is shown in the startup context and can be changed only
 
 For a supported cache, deploy, indexing, or test operation, prefer \`magento_workflow\`. For a different n98-magerun2 subcommand, use \`magerun2\` with an exact \`args: string[]\` vector, never a shell command or interpolation. When the user did not directly request execution, return its preview without \`execute: true\`; an executed generic magerun2 call requires \`execute: true\` and uses the same sole harness confirmation. Never send \`dev:console\` through \`magerun2\`: use the typed \`magento_php_repl\` tool instead.
 
-Environment lifecycle is explicit. Warden has known direct controls. SSH is always reported running and must never be started, stopped, or restarted. A local environment is agent-directed: when the user requests a start or stop, inspect the actual project lifecycle first, then call \`environment_start\` or \`environment_stop\` with the exact smallest command. Never guess a generic Docker, Compose, npm, or service command, and never affect unrelated host services. Use \`environment_set_status\` after a status inspection that does not itself start or stop the stack. Never inspect app/etc/env.php or credentials.`;
+Environment lifecycle is explicit. Warden has known direct controls. SSH is always reported running and must never be started, stopped, or restarted. A local environment is agent-directed: when the user requests a start or stop, inspect the actual project lifecycle first, then call \`environment_start\` or \`environment_stop\` with the exact smallest command. Never guess a generic Docker, Compose, npm, or service command, and never affect unrelated host services. Use \`environment_set_status\` after a status inspection that does not itself start or stop the stack. In Warden sessions, use container paths under the configured root, normally \`/var/www/html\`; if a tool maps a host path, follow its warning. Successful writes and edits return post-edit hints. Fix any reported Magento XML XSD validation warning before moving on. Never inspect app/etc/env.php or credentials.`;
 }

package/dist/environments/adapters/warden.d.ts

@@ -1,10 +1,16 @@
 import type { EnvironmentAdapter } from "#environments/adapter";
 import type { WardenEnvironment } from "#environments/model";
 export declare class WardenAdapter implements EnvironmentAdapter {
+    #private;
     readonly environment: WardenEnvironment;
     readonly cwd: string;
     constructor(environment: WardenEnvironment, cwd: string);
-    path(path: string): string;
+    /**
+     * Resolve a path into the Warden container before a routed command runs.
+     * Relative paths are container-relative; absolute paths may be either
+     * canonical container paths or host paths below the Warden project root.
+     */
+    path(candidate: string): string;
     command(argv: string[], target?: string): {
         file: string;
         args: string[];

package/dist/environments/adapters/warden.js

@@ -1,13 +1,30 @@
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { contain } from "#environments/path-policy";
 export class WardenAdapter {
     environment;
     cwd;
+    #hostRoot;
+    #containerRoot;
     constructor(environment, cwd) {
         this.environment = environment;
         this.cwd = cwd;
+        this.#hostRoot = resolve(cwd, environment.projectRoot);
+        this.#containerRoot = resolve(environment.root);
     }
-    path(path) {
-        return path.startsWith("/") ? path : `${this.environment.root}/${path}`;
+    /**
+     * Resolve a path into the Warden container before a routed command runs.
+     * Relative paths are container-relative; absolute paths may be either
+     * canonical container paths or host paths below the Warden project root.
+     */
+    path(candidate) {
+        if (!isAbsolute(candidate))
+            return contain(this.#containerRoot, candidate);
+        const absolute = resolve(candidate);
+        if (within(this.#containerRoot, absolute))
+            return absolute;
+        if (within(this.#hostRoot, absolute))
+            return contain(this.#containerRoot, relative(this.#hostRoot, absolute));
+        throw new Error(`Path is outside the Warden project and container roots: ${candidate}`);
     }
     command(argv, target) {
         const service = target
@@ -29,3 +46,7 @@ export class WardenAdapter {
         return { file: "warden", args: actionArgs, cwd: resolve(this.cwd, this.environment.projectRoot) };
     }
 }
+function within(root, candidate) {
+    const value = relative(root, candidate);
+    return value === "" || (value !== ".." && !value.startsWith(`..${sep}`));
+}

package/dist/integrations/pi/permissions.d.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type PermissionMode } from "#app/permission-mode";
 import type { Environment } from "#environments/model";
+export declare function permissionChoices(): PermissionMode[];
 export declare function requiresExecuteConfirmation(toolName: string, input: Record<string, unknown>): boolean;
 /** Return block/confirmation behavior; callers retain all hard capability constraints. */
 export declare function permissionDecision(mode: PermissionMode, environment: Environment, toolName: string, input: Record<string, unknown>): "allow" | "block" | "confirm";

package/dist/integrations/pi/permissions.js

@@ -3,6 +3,9 @@ import { refreshStatus } from "#app/status";
 import { runtime } from "#integrations/pi/session";
 const workspaceMutations = new Set(["write", "edit"]);
 const stoppedAllowed = new Set(["environment_status", "environment_start", "environment_stop", "environment_set_status"]);
+export function permissionChoices() {
+    return [...permissionModes];
+}
 export function requiresExecuteConfirmation(toolName, input) {
     return ["environment_start", "environment_stop"].includes(toolName) || ((toolName === "mage2gen_generate_module" || toolName === "magento_workflow" || toolName === "magerun2") && input.execute === true);
 }
@@ -26,9 +29,13 @@ async function confirm(ctx, title, message) {
 /** The sole MerchantDuo confirmation gate. YOLO removes dialogs, never hard constraints. */
 export default function permissions(pi) {
     pi.registerCommand("duo-switch-permissions", { description: "Set this session's permission mode: read-only, normal, or yolo.", handler: async (args, ctx) => {
-            const mode = args.trim();
-            if (!permissionModes.includes(mode)) {
-                ctx.ui.notify("Choose one of: read-only, normal, yolo", "error");
+            const choices = permissionChoices();
+            const typed = args.trim();
+            const mode = typed || (ctx.hasUI ? await ctx.ui.select("Select session permission mode", choices) : undefined);
+            if (!mode)
+                return;
+            if (!choices.includes(mode)) {
+                ctx.ui.notify(`Choose one of: ${choices.join(", ")}`, "error");
                 return;
             }
             await runtime.boot(ctx.cwd);

package/dist/integrations/pi/workspace.d.ts

@@ -16,6 +16,7 @@ type SearchParameters = {
  */
 export declare function searchCommand(params: SearchParameters, path: string): string;
 export declare function workspacePath(backend: EnvironmentBackend, cwd: string, candidate: string): string;
+export declare function wardenHostPathWarning(backend: EnvironmentBackend, cwd: string, candidate: string): string | undefined;
 /** Return only a declared MerchantDuo skill asset; project files remain environment-routed. */
 export declare function packagedSkillPath(candidate: string): string | undefined;
 export {};

package/dist/integrations/pi/workspace.js

@@ -1,9 +1,10 @@
 import { access as hostAccess, readFile as hostReadFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { Type } from "typebox";
 import { createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "@earendil-works/pi-coding-agent";
 import { runtime } from "#integrations/pi/session";
 import { packagePath } from "#shared/package-paths";
+import { postEditHints, validateMagentoXml } from "#workflows/post-edit";
 const shell = (value) => `'${value.replace(/'/g, "'\\''")}'`;
 const result = (value) => ({ content: [{ type: "text", text: value }], details: {} });
 const packageSkillRoots = [
@@ -34,9 +35,19 @@ function registerFileTools(pi) {
     const localRead = createReadToolDefinition(process.cwd());
     const localWrite = createWriteToolDefinition(process.cwd());
     const localEdit = createEditToolDefinition(process.cwd());
-    pi.registerTool({ ...localRead, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createReadToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
-    pi.registerTool({ ...localWrite, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createWriteToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
-    pi.registerTool({ ...localEdit, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); return createEditToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); } });
+    pi.registerTool({ ...localRead, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createReadToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendNotice(response, wardenHostPathWarning(state.backend, ctx.cwd, params.path)); } });
+    pi.registerTool({ ...localWrite, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createWriteToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendPostEdit(response, state.backend, ctx.cwd, params.path, signal); } });
+    pi.registerTool({ ...localEdit, async execute(id, params, signal, update, ctx) { const state = await runtime.boot(ctx.cwd); const response = await createEditToolDefinition(ctx.cwd, { operations: fileOps(state.backend, ctx.cwd) }).execute(id, params, signal, update, ctx); return appendPostEdit(response, state.backend, ctx.cwd, params.path, signal); } });
+}
+async function appendPostEdit(response, backend, cwd, path, signal) {
+    const target = workspacePath(backend, cwd, path);
+    const validation = await validateMagentoXml(backend, target, signal);
+    return appendNotice(response, [wardenHostPathWarning(backend, cwd, path), ...postEditHints(path), validation].filter((value) => Boolean(value)).join("\n"));
+}
+function appendNotice(response, notice) {
+    if (!notice)
+        return response;
+    return { ...response, content: [...response.content, { type: "text", text: `MerchantDuo: ${notice}` }] };
 }
 function fileOps(backend, cwd) {
     const readFile = async (path) => {
@@ -58,8 +69,27 @@ function fileOps(backend, cwd) {
             throw new Error("Path is inaccessible"); }, mkdir: async (path) => { const response = await backend.run(["mkdir", "-p", workspacePath(backend, cwd, path)]); if (response.exitCode)
             throw new Error(response.stderr || "Cannot create directory"); } };
 }
-export function workspacePath(backend, cwd, candidate) { const full = resolve(cwd, candidate); const value = relative(resolve(cwd), full); if (value === ".." || value.startsWith("../"))
-    throw new Error(`Path escapes workspace: ${candidate}`); return backend.path(value); }
+export function workspacePath(backend, cwd, candidate) {
+    if (backend.environment.type === "warden" && isAbsolute(candidate)) {
+        const containerPath = resolve(candidate);
+        if (contains(resolve(backend.environment.root), containerPath))
+            return containerPath;
+    }
+    const full = resolve(cwd, candidate);
+    const value = relative(resolve(cwd), full);
+    if (value === ".." || value.startsWith("../"))
+        throw new Error(`Path escapes workspace: ${candidate}`);
+    return backend.path(value);
+}
+export function wardenHostPathWarning(backend, cwd, candidate) {
+    if (backend.environment.type !== "warden" || !isAbsolute(candidate))
+        return undefined;
+    const hostPath = resolve(candidate);
+    if (!contains(resolve(cwd), hostPath))
+        return undefined;
+    const value = relative(resolve(cwd), hostPath);
+    return `Warden path warning: ${candidate} was mapped to ${backend.path(value)}. This session runs inside Warden; use the container path next time.`;
+}
 /** Return only a declared MerchantDuo skill asset; project files remain environment-routed. */
 export function packagedSkillPath(candidate) {
     const full = resolve(candidate);

package/dist/workflows/post-edit.d.ts

@@ -0,0 +1,7 @@
+import type { EnvironmentBackend } from "#environments/backend";
+/** Keep immediate post-edit guidance narrow; operational work remains an explicit request. */
+export declare function postEditHints(path: string): string[];
+export declare function isMagentoXml(path: string): boolean;
+/** Validate changed Magento XML in its own selected environment using Magento's URN resolver. */
+export declare function validateMagentoXml(backend: EnvironmentBackend, path: string, signal?: AbortSignal): Promise<string>;
+export declare function xmlValidationCommand(path: string): string[];

package/dist/workflows/post-edit.js

@@ -0,0 +1,51 @@
+const xsdValidator = String.raw `
+$file = $argv[1] ?? '';
+libxml_use_internal_errors(true);
+$dom = new DOMDocument();
+if (!$dom->load($file)) {
+    foreach (libxml_get_errors() as $error) fwrite(STDERR, trim($error->message) . " at line " . $error->line . "\n");
+    exit(2);
+}
+$root = $dom->documentElement;
+$schema = $root ? $root->getAttributeNS('http://www.w3.org/2001/XMLSchema-instance', 'noNamespaceSchemaLocation') : '';
+if (!$schema || strpos($schema, 'urn:magento:') !== 0) {
+    fwrite(STDERR, "Magento XML must declare xsi:noNamespaceSchemaLocation with a urn:magento schema.\n");
+    exit(2);
+}
+require getcwd() . '/app/bootstrap.php';
+$errors = Magento\Framework\Config\Dom::validateDomDocument($dom, $schema);
+if ($errors) {
+    foreach ($errors as $error) fwrite(STDERR, (string)$error . "\n");
+    exit(2);
+}
+echo "Magento XML XSD validation passed.\n";
+`;
+/** Keep immediate post-edit guidance narrow; operational work remains an explicit request. */
+export function postEditHints(path) {
+    const value = path.toLowerCase();
+    const hints = ["Inspect the changed file and its closest Magento precedent before continuing."];
+    if (value.endsWith(".php") || value.endsWith(".phtml"))
+        hints.push("Use magento_workflow action=syntax-check when PHP syntax verification is relevant.");
+    if (value.endsWith(".xml"))
+        hints.push("Review the XSD result below; preview a cache clean only when this configuration change requires it.");
+    if (value.endsWith("etc/module.xml") || value.endsWith("db_schema.xml") || value.endsWith("composer.json"))
+        hints.push("This may require setup:upgrade; explain the evidence and use magento_workflow only after the user directly requests execution.");
+    return hints;
+}
+export function isMagentoXml(path) {
+    return path.toLowerCase().endsWith(".xml")
+        && /(?:^|\/)(?:app\/(?:code|design)|vendor)\//.test(path.replace(/\\/g, "/"));
+}
+/** Validate changed Magento XML in its own selected environment using Magento's URN resolver. */
+export async function validateMagentoXml(backend, path, signal) {
+    if (!isMagentoXml(path))
+        return "";
+    const output = await backend.run(xmlValidationCommand(path), { signal });
+    const detail = `${output.stdout}${output.stderr}`.trim();
+    return output.exitCode === 0
+        ? detail || "Magento XML XSD validation passed."
+        : `Warning: Magento XML XSD validation failed for ${path}: ${detail || "validation could not run."}`;
+}
+export function xmlValidationCommand(path) {
+    return ["php", "-r", xsdValidator, path];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merchantduo/code",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.2",
   "private": false,
   "description": "Magento-native Pi-based Coding Agent",
   "type": "module",

package/skills/magento-2.4/SKILL.md

@@ -1,8 +1,247 @@
 ---
-name: magento-24x
-description: Magento Open Source and Adobe Commerce 2.4 implementation guidance.
+name: magento-extension-best-practices
+description: Choose and review Magento Open Source / Adobe Commerce 2.4.x extension architecture. Load for non-trivial work involving DI, plugins, preferences, observers, service contracts, persistence, schema/XML, caching, indexers, queues, Admin UI, Luma, Hyvä, REST, GraphQL, security, or testing.
 ---
 
+# Magento Extension Best Practices
+
+## Extension Decision Order
+
+When changing existing behavior, prefer the first mechanism that fully solves the requirement:
+
+1. XML or declarative configuration.
+2. Public `@api` contract or documented extension point.
+3. Existing strategy, pool, composite, provider, resolver, or other composition mechanism.
+4. Semantic event + observer for an independent reaction.
+5. `before` / `after` plugin for a narrow public-method change.
+6. `around` plugin only when execution must be wrapped, skipped, or replaced.
+7. Preference/inheritance for deliberate implementation replacement or non-interceptable behavior.
+8. Undocumented internals only as an isolated, upgrade-sensitive last resort.
+
+## Module Boundaries
+
+- Prefer public `@api` contracts across modules.
+- Isolate unavoidable concrete non-`@api` dependencies behind your own adapter/service and regression coverage.
+- Put package dependencies in `composer.json`.
+- Use `<sequence>` only when Magento config/setup/view load order matters.
+- Create interfaces for public contracts, substitution boundaries, multiple implementations, or deliberately stable module boundaries; not for every service.
+
+## DI and Object Creation
+
+- **DI:** normal dependency known at wiring time.
+- **Factory:** runtime/transient/entity instance creation.
+- **Proxy:** lazy-load an expensive dependency that is often unused.
+- **Virtual type:** same class with different constructor arguments in a specific injection context.
+- **Preference:** deliberate implementation binding/replacement.
+
+Do not use factories to hide ordinary dependencies or proxies as generic performance decoration.
+
+## Plugins, Preferences, Events
+
+### Plugins
+
+- `before`: small argument changes.
+- `after`: result changes.
+- `around`: only when wrapping/skipping/replacing execution is required.
+- If `before` or `after` works, do not use `around`.
+- Keep plugins small and stateless.
+- Delegate business logic to services.
+- Do not plugin your own module when direct composition/refactoring is available.
+- Interception is for supported public methods; final/non-public/static methods and constructors are not normal plugin targets.
+
+### Preferences / Inheritance
+
+Preferences are valid for deliberate implementation binding or full replacement.
+
+Avoid a preference merely to change one public method. If replacement is necessary:
+
+- override the minimum surface;
+- do not copy whole core/vendor classes;
+- isolate dependency on internals;
+- add upgrade regression coverage.
+
+### Events
+
+Use observers for existing semantic events and independent side effects. Use plugins when changing a method's arguments, result, or execution.
+
+Keep observers small and delegate work. Prefer area-specific `events.xml` when applicable. Do not rely on event-payload mutation as a hidden behavior override.
+
+## Data Access
+
+Repositories are module/API boundaries, not a universal internal persistence rule.
+
+Use repositories/service contracts for public or cross-module entity access, standard CRUD/list contracts, `SearchCriteria`, API data interfaces, and extension attributes.
+
+Internal code may use:
+
+- collections for filtering/list/batch reads;
+- resource models for persistence;
+- dedicated query services for joins, reports, projections, or aggregates;
+- `ResourceConnection` for deliberate bulk/index/import work.
+
+Avoid new Active Record-style `$model->load()` / `$model->save()` usage.
+
+### Direct SQL
+
+Direct SQL is acceptable in resource/query layers when Magento entity lifecycle is intentionally unnecessary.
+
+Use Magento DB adapters, resolved table names, and parameter bindings. Do not bypass required validation, business invariants, cache invalidation, events, or indexer/MView behavior.
+
+### Performance and Concurrency
+
+- Avoid repository/entity loads in large loops.
+- Prevent N+1 extension-attribute and GraphQL loading.
+- Prefer batch reads, joins, collections, or query services.
+- Keep DB transactions small; avoid network calls inside long transactions.
+- Use DB constraints, atomic updates, locks, or retries for concurrency-critical invariants.
+- Make retryable queue/cron/bulk handlers idempotent where duplicate delivery or overlap is possible.
+
+## Declarative Configuration
+
+Before runtime PHP, check for an existing Magento mechanism:
+
+`di.xml`, `events.xml`, `routes.xml`, `webapi.xml`, `acl.xml`, `system.xml`, `config.xml`, `menu.xml`, `email_templates.xml`, `cron.xml`, `communication.xml`, `queue_*`, `indexer.xml`, `mview.xml`, `extension_attributes.xml`, layout XML, UI component XML, `db_schema.xml`.
+
+Respect global vs area-scoped configuration. Do not assume every XML type merges identically.
+
+## Schema Changes
+
+For new Magento 2.4.x modules:
+
+- prefer `db_schema.xml` for schema;
+- use data patches for one-time data changes;
+- use schema patches only when imperative schema work is genuinely needed;
+- treat `InstallSchema`, `UpgradeSchema`, `InstallData`, and `UpgradeData` as legacy patterns.
+
+For large production tables, review locking, backfills, deployment safety, indexes, and foreign-key behavior.
+
+## Cache and Indexers
+
+Treat FPC as an architectural constraint.
+
+- Avoid broad `cacheable="false"`.
+- Keep customer-specific data out of public FPC output; use the proper private-content mechanism.
+- Return correct cache identities/tags.
+- Never global `cache:flush` after normal writes.
+- Invalidate only relevant cache data or rely on Magento lifecycle invalidation.
+- Include store/customer/website/authorization dimensions in cache variation when required.
+
+Code must work with indexers in both **Update on Save** and **Update by Schedule** modes.
+
+Do not full-reindex after every write. With direct SQL, verify index invalidation and MView changelog behavior.
+
+## Async Work
+
+Use message queues for slow, high-volume, retryable, or integration-heavy work.
+
+Use cron mainly for scheduling/discovery; use consumers for scalable units of work. Prefer Magento queue configuration over bespoke polling infrastructure.
+
+## Frontend
+
+### Luma
+
+Prefer:
+
+1. Layout XML.
+2. ViewModel.
+3. Minimal template override.
+4. RequireJS mixin for existing AMD behavior.
+5. New JS module/component with declarative initialization.
+6. Full replacement only when necessary.
+
+Use ViewModels for template-facing behavior/data. Prefer `data-mage-init` / `x-magento-init`. Avoid copying whole vendor PHTML/JS files. Do not instantiate services in templates.
+
+Use Knockout/UI Components where the existing Magento surface already uses them, especially checkout and complex Admin UI.
+
+### Hyvä
+
+Treat Hyvä as a separate frontend runtime.
+
+- Do not assume RequireJS, Knockout, jQuery, or Luma `customer-data` on normal Hyvä pages.
+- Prefer Alpine.js and Hyvä ViewModels/private-content mechanisms.
+- Check installed Hyvä versions before relying on Tailwind/Alpine details.
+- Use compatibility modules or isolated Luma fallback when appropriate.
+
+## Admin
+
+Use UI Components for standard Magento grids/forms where data sources, filters, bookmarks, mass actions, or existing component hierarchies are useful.
+
+For simple bespoke pages, layout + block/ViewModel/template may be clearer.
+
+Authorization must be backend-enforced. Controllers/routes and relevant UI data endpoints need proper ACL; hiding UI elements is not authorization.
+
+## REST / SOAP / GraphQL
+
+Expose stable service-contract methods through `webapi.xml` with correct ACL. Reuse business services across transports.
+
+Keep GraphQL resolvers thin. Delegate logic, batch-load to avoid N+1, enforce authentication plus ownership/resource access, and return cache identities when required. Prefer token-based API auth over PHP-session-dependent API designs.
+
+## State Boundaries
+
+Do not inject checkout/customer/backend sessions, `RequestInterface`, cookies, or implicit request state into reusable business services.
+
+Adapters should extract explicit context such as `customerId`, `quoteId`, `storeId`, or `websiteId` and pass it to services.
+
+## Security
+
+Verify:
+
+- context-appropriate output escaping;
+- CSRF/form-key and correct HTTP method for browser state changes;
+- Admin/API/GraphQL ACL and object ownership;
+- bound SQL parameters;
+- safe filesystem/upload handling and validation;
+- no unsafe unserialization or command execution on untrusted input.
+
+## Testing
+
+- **Unit:** pure services, value objects, algorithms.
+- **Integration:** DI/XML, DB, repositories, plugins, observers, indexers, cache.
+- **API functional:** REST/GraphQL contracts, auth, serialization.
+- **MFTF:** critical browser workflows.
+
+Test observable behavior, not interceptor implementation details. Add regression tests for upgrade-sensitive overrides.
+
+## Red Flags
+
+Redesign or explicitly justify:
+
+- `ObjectManager::get()` in feature code;
+- `$model->load()` / `$model->save()` in new code;
+- large observers;
+- business workflows in plugins;
+- `around` for simple argument/result changes;
+- preference for one public method;
+- copied core/vendor classes or unnecessary copied PHTML/JS;
+- repository/entity loads in large loops;
+- global cache flush after normal writes;
+- session/request state deep in business logic;
+- direct SQL bypassing required Magento lifecycle;
+- UI Components for every Admin page;
+- direct edits under `vendor/`.
+
+## Final Review
+
+Before finalizing an implementation, verify:
+
+1. Is there already an XML/declarative solution?
+2. Is there a public API or narrower documented extension point?
+3. Am I replacing more code than necessary?
+4. Am I relying on non-public internals?
+5. Could composition replace inheritance/preference?
+6. Is `around` truly required?
+7. Is business logic trapped in a plugin/observer/resolver/controller?
+8. Is the data-access method appropriate, or merely habitual?
+9. Can this create N+1 queries?
+10. Does request/session state leak into reusable services?
+11. Is it correct under FPC, indexers/MView, retries, concurrency, and production DI compilation?
+12. Are ACL, ownership, escaping, SQL bindings, and CSRF correct?
+13. Will it survive the next Magento/vendor patch update?
+
+For production-sensitive changes, validate relevant paths with `setup:di:compile`, production mode, static content deployment where applicable, cache/indexer modes, cron/consumers, and Magento Coding Standard checks.
+
+## MerchantDuo Magento 2.4 session workflow
+
 # Magento 2.4
 
 Confirm the installed Magento version, edition, and deployment mode before changing framework behavior. Prefer a focused module, declarative schema and data patches, dependency injection, service contracts, layout XML, and Magento CLI validation. Do not read `app/etc/env.php`.