proteum 2.5.8 → 2.5.10

package/cli/commands/session.ts

@@ -4,7 +4,13 @@ import { spawn } from 'child_process';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
-import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+import {
+    buildDevSessionLoginUrl,
+    devSessionStartPath,
+    normalizeDevSessionRedirectPath,
+    type TDevSessionErrorResponse,
+    type TDevSessionStartResponse,
+} from '../../common/dev/session';
 
 const localSessionResultMarker = '__PROTEUM_SESSION_RESULT__';
 
@@ -13,6 +19,7 @@ type TResolvedSessionOutput = {
     user: TDevSessionStartResponse['user'];
     session: TDevSessionStartResponse['session'];
     browserCookie: string;
+    browserLoginUrl: string;
     curlCookieHeader: string;
     playwright: {
         cookies: Array<{
@@ -28,6 +35,13 @@ type TResolvedSessionOutput = {
 };
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const normalizeRedirectPath = (value: string): string => {
+    try {
+        return normalizeDevSessionRedirectPath(value);
+    } catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+};
 
 const getRouterPortFromManifest = () => {
     const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
@@ -82,7 +96,7 @@ const requestSession = async (email: string, role: string) => {
 
     for (const baseUrl of getRouterBaseUrls()) {
         try {
-            const response = await got(`${baseUrl}/__proteum/session/start`, {
+            const response = await got(`${baseUrl}${devSessionStartPath}`, {
                 method: 'POST',
                 json: role ? { email, role } : { email },
                 responseType: 'json',
@@ -92,7 +106,7 @@ const requestSession = async (email: string, role: string) => {
 
             if (response.statusCode >= 400) {
                 if (response.statusCode === 404 && !hasStructuredSessionError(response.body as TDevSessionErrorResponse | object | string | undefined)) {
-                    attempts.push(`${baseUrl}/__proteum/session/start: returned 404`);
+                    attempts.push(`${baseUrl}${devSessionStartPath}: returned 404`);
                     continue;
                 }
 
@@ -109,7 +123,7 @@ const requestSession = async (email: string, role: string) => {
             if (error instanceof UsageError) throw error;
 
             const message = error instanceof Error ? error.message : String(error);
-            attempts.push(`${baseUrl}/__proteum/session/start: ${message}`);
+            attempts.push(`${baseUrl}${devSessionStartPath}: ${message}`);
         }
     }
 
@@ -124,9 +138,13 @@ const requestSession = async (email: string, role: string) => {
 
 const buildSessionOutput = ({
     baseUrl,
+    redirect,
+    role,
     response,
 }: {
     baseUrl: string;
+    redirect: string;
+    role: string;
     response: TDevSessionStartResponse;
 }): TResolvedSessionOutput => {
     const expires = Math.floor(Date.parse(response.session.expiresAt) / 1000);
@@ -137,6 +155,12 @@ const buildSessionOutput = ({
         user: response.user,
         session: response.session,
         browserCookie: `${response.session.cookieName}=${response.session.token}; Path=/`,
+        browserLoginUrl: buildDevSessionLoginUrl({
+            baseUrl,
+            email: response.user.email,
+            redirect,
+            role,
+        }),
         curlCookieHeader: `Cookie: ${response.session.cookieName}=${response.session.token}`,
         playwright: {
             cookies: [
@@ -170,6 +194,8 @@ const renderSession = (value: TResolvedSessionOutput) =>
         JSON.stringify(value.playwright, null, 2),
         'Browser Cookie',
         value.browserCookie,
+        'Browser Login URL',
+        value.browserLoginUrl,
     ].join('\n');
 
 const runLocalSession = async (email: string, role: string) => {
@@ -232,6 +258,7 @@ const runLocalSession = async (email: string, role: string) => {
 export const run = async () => {
     const email = typeof cli.args.email === 'string' ? cli.args.email.trim() : '';
     const role = typeof cli.args.role === 'string' ? cli.args.role.trim() : '';
+    const redirect = normalizeRedirectPath(typeof cli.args.redirect === 'string' ? cli.args.redirect : '/');
     const shouldPrintJson = cli.args.json === true;
     const shouldUseRemoteServer =
         (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
@@ -242,7 +269,11 @@ export const run = async () => {
     }
 
     const resolved = buildSessionOutput(
-        shouldUseRemoteServer ? await requestSession(email, role) : await runLocalSession(email, role),
+        {
+            ...(shouldUseRemoteServer ? await requestSession(email, role) : await runLocalSession(email, role)),
+            redirect,
+            role,
+        },
     );
 
     if (shouldPrintJson) {

package/cli/commands/verify.ts

@@ -1149,7 +1149,12 @@ const runChangedVerify = async () => {
             code: 'changed/check-failed',
             message: `Verification check "${execution.checkId}" failed with exit code ${execution.exitCode ?? 'unknown'}.`,
             source: 'changed',
-            details: [`command=${execution.command}`, `cwd=${execution.cwd}`, `durationMs=${execution.durationMs}`],
+            details: [
+                `command=${execution.command}`,
+                `cwd=${execution.cwd}`,
+                `durationMs=${execution.durationMs}`,
+                'fix=Fix the failing surface and re-run npx proteum verify changed; broader gates only per the root AGENTS.md Verification Policy.',
+            ],
         }));
 
     return finalizeResult({

package/cli/compiler/client/index.ts

@@ -12,6 +12,7 @@ import { rspack, type Configuration, type Module } from '@rspack/core';
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { createClientBundleAnalysisPlugins } from '../common/bundleAnalysis';
 import { toRspackAliases } from '../common/rspackAliases';
+import { resolveUiSingletonAliases } from '../common/uiSingletons';
 import identityAssets from './identite';
 import cli from '../..';
 import { logVerbose } from '../../runtime/verbose';
@@ -35,7 +36,9 @@ const getFrameworkSourceRoot = () => {
     return activeCoreRoot;
 };
 
-const resolveFromAppOrCore = (_app: App, request: string) => cli.paths.resolveRequest(request);
+const resolveFromAppOrCore = (request: string) => cli.paths.resolveRequest(request, { preferApp: true });
+const resolvePackageRootFromAppOrCore = (packageName: string) =>
+    cli.paths.resolvePackageRoot(packageName, { preferApp: true });
 const rewriteFrameworkAliasTargets = (aliases: Record<string, string | string[]>) => {
     const visibleFrameworkRoots = [
         ...cli.paths.getVisiblePackageInstallRoots('proteum'),
@@ -145,9 +148,13 @@ export default function createCompiler(
     const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['proteum'] = frameworkSourceRoot;
     rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
-    rspackAliases['preact/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
-    rspackAliases['react/jsx-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-runtime');
-    rspackAliases['react/jsx-dev-runtime$'] = resolveFromAppOrCore(app, 'preact/jsx-dev-runtime');
+    Object.assign(
+        rspackAliases,
+        resolveUiSingletonAliases({
+            resolvePackageRoot: resolvePackageRootFromAppOrCore,
+            resolveRequest: resolveFromAppOrCore,
+        }),
+    );
 
     debug && console.log('client aliases', rspackAliases);
     const config: Configuration = {

package/cli/compiler/common/uiSingletons.ts

@@ -0,0 +1,76 @@
+type TUiSingletonResolvers = {
+    resolvePackageRoot: (packageName: string) => string;
+    resolveRequest: (request: string) => string;
+};
+
+const uiSingletonPackages = ['preact', 'preact-render-to-string', 'react', 'react-dom'];
+
+const uiSingletonPackageAliases: Array<{ alias: string; packageName: string }> = [
+    { alias: 'preact', packageName: 'preact' },
+    { alias: 'preact-render-to-string', packageName: 'preact-render-to-string' },
+];
+
+const uiSingletonRequestAliases: Array<{ alias: string; request: string }> = [
+    { alias: 'preact$', request: 'preact' },
+    { alias: 'preact/hooks$', request: 'preact/hooks' },
+    { alias: 'preact/compat$', request: 'preact/compat' },
+    { alias: 'preact/compat/client$', request: 'preact/compat/client' },
+    { alias: 'preact/jsx-runtime$', request: 'preact/jsx-runtime' },
+    { alias: 'preact/jsx-dev-runtime$', request: 'preact/jsx-dev-runtime' },
+    { alias: 'react$', request: 'preact/compat' },
+    { alias: 'react-dom$', request: 'preact/compat' },
+    { alias: 'react-dom/client$', request: 'preact/compat/client' },
+    { alias: 'react-dom/test-utils$', request: 'preact/test-utils' },
+    { alias: 'react/jsx-runtime$', request: 'preact/jsx-runtime' },
+    { alias: 'react/jsx-dev-runtime$', request: 'preact/jsx-dev-runtime' },
+    { alias: 'preact-render-to-string$', request: 'preact-render-to-string' },
+];
+
+const uiSingletonServerExternalRequests: Array<{ request: string; resolvedRequest: string }> = [
+    { request: 'preact', resolvedRequest: 'preact' },
+    { request: 'preact/hooks', resolvedRequest: 'preact/hooks' },
+    { request: 'preact/compat', resolvedRequest: 'preact/compat' },
+    { request: 'preact/compat/client', resolvedRequest: 'preact/compat/client' },
+    { request: 'preact/jsx-runtime', resolvedRequest: 'preact/jsx-runtime' },
+    { request: 'preact/jsx-dev-runtime', resolvedRequest: 'preact/jsx-dev-runtime' },
+    { request: 'preact/test-utils', resolvedRequest: 'preact/test-utils' },
+    { request: 'react', resolvedRequest: 'preact/compat' },
+    { request: 'react-dom', resolvedRequest: 'preact/compat' },
+    { request: 'react-dom/client', resolvedRequest: 'preact/compat/client' },
+    { request: 'react-dom/test-utils', resolvedRequest: 'preact/test-utils' },
+    { request: 'react/jsx-runtime', resolvedRequest: 'preact/jsx-runtime' },
+    { request: 'react/jsx-dev-runtime', resolvedRequest: 'preact/jsx-dev-runtime' },
+];
+
+export const isUiSingletonRequest = (request: string | undefined) =>
+    typeof request === 'string' &&
+    uiSingletonPackages.some((packageName) => request === packageName || request.startsWith(`${packageName}/`));
+
+export const resolveUiSingletonAliases = ({ resolvePackageRoot, resolveRequest }: TUiSingletonResolvers) => ({
+    ...Object.fromEntries(
+        uiSingletonRequestAliases.map(({ alias, request }) => [
+            alias,
+            resolveRequest(request),
+        ]),
+    ),
+    ...Object.fromEntries(
+        uiSingletonPackageAliases.map(({ alias, packageName }) => [
+            alias,
+            resolvePackageRoot(packageName),
+        ]),
+    ),
+});
+
+export const resolveUiSingletonServerExternalRequest = (
+    request: string | undefined,
+    resolveRequest: TUiSingletonResolvers['resolveRequest'],
+) => {
+    if (request === undefined) return undefined;
+
+    const exactExternalRequest = uiSingletonServerExternalRequests.find((entry) => entry.request === request);
+    if (exactExternalRequest) return resolveRequest(exactExternalRequest.resolvedRequest);
+
+    if (request.startsWith('preact/')) return resolveRequest(request);
+
+    return undefined;
+};

package/cli/compiler/server/externals.ts

@@ -0,0 +1,35 @@
+type TResolveRequestOptions = { preferApp: boolean };
+
+type TResolveServerExternalRequestOptions = {
+    context?: string;
+    frameworkRoots: string[];
+    request: string;
+    resolveRequest: (request: string, options: TResolveRequestOptions) => string;
+};
+
+const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
+
+export const isFrameworkSourceContext = (context: string | undefined, frameworkRoots: string[]) => {
+    const normalizedContext = normalizeModulePath(context);
+
+    return frameworkRoots.some((rootPath) => {
+        const normalizedRootPath = normalizeModulePath(rootPath);
+
+        return normalizedContext === normalizedRootPath || normalizedContext.startsWith(normalizedRootPath + '/');
+    });
+};
+
+export const resolveServerExternalRequest = ({
+    context,
+    frameworkRoots,
+    request,
+    resolveRequest,
+}: TResolveServerExternalRequestOptions) => {
+    try {
+        return resolveRequest(request, {
+            preferApp: !isFrameworkSourceContext(context, frameworkRoots),
+        });
+    } catch {
+        return request;
+    }
+};

package/cli/compiler/server/index.ts

@@ -10,6 +10,12 @@ import { type Configuration } from '@rspack/core';
 import cli from '@cli';
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { toRspackAliases } from '../common/rspackAliases';
+import {
+    isUiSingletonRequest,
+    resolveUiSingletonAliases,
+    resolveUiSingletonServerExternalRequest,
+} from '../common/uiSingletons';
+import { resolveServerExternalRequest } from './externals';
 
 // Type
 import type { App } from '../../app';
@@ -50,6 +56,9 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_routes: [app.paths.server.generated + '/routes.ts'],
     __proteum_dev_controllers: [app.paths.server.generated + '/controllers.ts'],
 });
+const resolveFromAppOrCore = (request: string) => cli.paths.resolveRequest(request, { preferApp: true });
+const resolvePackageRootFromAppOrCore = (packageName: string) =>
+    cli.paths.resolvePackageRoot(packageName, { preferApp: true });
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
 const getFrameworkSourceRoot = () => {
     const installedCoreRoot = cli.paths.framework.installedRoot
@@ -119,6 +128,13 @@ export default function createCompiler(
     const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['proteum'] = frameworkSourceRoot;
     rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
+    Object.assign(
+        rspackAliases,
+        resolveUiSingletonAliases({
+            resolvePackageRoot: resolvePackageRootFromAppOrCore,
+            resolveRequest: resolveFromAppOrCore,
+        }),
+    );
 
     debug &&
         console.log(
@@ -158,27 +174,42 @@ export default function createCompiler(
             './client-manifest.json',
 
             // node_modules
-            function ({ request }, callback) {
+            function ({ context, request }, callback) {
+                if (request === undefined) return callback();
+
+                const uiSingletonExternalRequest = resolveUiSingletonServerExternalRequest(request, resolveFromAppOrCore);
+                if (uiSingletonExternalRequest !== undefined) {
+                    return callback(undefined, 'commonjs ' + uiSingletonExternalRequest);
+                }
+
                 const shouldCompile =
-                    request !== undefined &&
                     // Local files
-                    (request[0] === '.' ||
-                        request[0] === '/' ||
-                        // Aliased modules
-                        app.aliases.server.containsAlias(request) ||
-                        // TODO: proteum.conf: compile: include
-                        app.isTranspileModuleRequest(request) ||
-                        // Compile proteum modules
-                        request.startsWith('proteum') ||
-                        // React-based UI packages must pass through the alias layer on the server,
-                        // otherwise SSR can mix real React packages with the Preact compat runtime.
-                        serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix)));
+                    request[0] === '.' ||
+                    request[0] === '/' ||
+                    // Aliased modules
+                    app.aliases.server.containsAlias(request) ||
+                    // TODO: proteum.conf: compile: include
+                    app.isTranspileModuleRequest(request) ||
+                    // Compile proteum modules
+                    request.startsWith('proteum') ||
+                    // React/Preact singleton packages and React-based UI packages must pass through the alias layer on the server,
+                    // otherwise SSR can mix real React packages with the Preact compat runtime.
+                    isUiSingletonRequest(request) ||
+                    serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix));
 
                 //console.log('isNodeModule', request, isNodeModule);
 
                 if (!shouldCompile) {
-                    // Externalize to a commonjs module using the request path
-                    return callback(undefined, 'commonjs ' + request);
+                    // Resolve server externals from their source owner. Bare runtime requires from
+                    // the dev output can otherwise hit the framework node_modules symlink first.
+                    const resolvedRequest = resolveServerExternalRequest({
+                        context,
+                        frameworkRoots,
+                        request,
+                        resolveRequest: (externalRequest, options) => cli.paths.resolveRequest(externalRequest, options),
+                    });
+
+                    return callback(undefined, 'commonjs ' + resolvedRequest);
                 }
 
                 // Continue without externalizing the import

package/cli/presentation/commands.ts

@@ -594,7 +594,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'session',
         category: 'Manifest and contracts',
         summary: 'Mint a dev-only auth session token and cookie payload for a known user.',
-        usage: 'proteum session <email> [--role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum session <email> [--role <role>] [--redirect <path>] [--port <port>|--url <baseUrl>] [--json]',
         bestFor:
             'Starting browser or API automation from an authenticated state without driving the login UI, while still using the app-configured auth service.',
         examples: [
@@ -606,11 +606,16 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 description: 'Mint a GOD session for unique.domains and print machine-readable cookie data',
                 command: 'proteum session god@example.com --role GOD --json',
             },
+            {
+                description: 'Print a browser login URL that sets the cookie and opens a protected page',
+                command: 'proteum session admin@example.com --port 3101 --redirect /admin --json',
+            },
         ],
         notes: [
             'Sessions are available only in dev mode and use the auth service registered on the current app router.',
             'You must provide the target user email explicitly; Proteum does not guess your admin account universally across apps.',
             'The command returns a token plus Playwright-ready cookie JSON so agents can inject the session into a browser context directly.',
+            'The command also returns a browser login URL that works on localhost dev servers, sets the same session cookie, and redirects to a local path.',
             'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, creates the session, prints the payload, and exits.',
         ],
         status: 'experimental',

package/cli/runtime/commands.ts

@@ -617,6 +617,7 @@ class SessionCommand extends ProteumCommand {
     public role = Option.String('--role', { description: 'Require the resolved user to have the given role.' });
     public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
     public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public redirect = Option.String('--redirect', { description: 'Local path used by the browser login URL.' });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public args = Option.Rest();
 
@@ -628,6 +629,7 @@ class SessionCommand extends ProteumCommand {
             role: this.role ?? '',
             port: this.port ?? '',
             url: this.url ?? '',
+            redirect: this.redirect ?? '',
             json: this.json,
         });
 

package/cli/scaffold/index.ts

@@ -556,6 +556,9 @@ export const runCreateScaffold = async () => {
 
     result.notes.push(...plan.notes);
     result.nextSteps.push(...plan.nextSteps);
+    result.nextSteps.push(
+        'Adapt the generated code to the real feature and record non-obvious decisions as why-comments per `CODING_STYLE.md` (`Decision and context comments`).',
+    );
     printResult(result);
 };
 

package/cli/scaffold/templates.ts

@@ -22,7 +22,15 @@ export const createPageTemplate = ({
     routePath: string;
     heading: string;
     message: string;
-}) => `import { definePageRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { definePageRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- PAGE
+----------------------------------*/
 
 export default definePageRoute({
     path: ${JSON.stringify(routePath)},
@@ -53,7 +61,15 @@ export const createControllerTemplate = ({
     appIdentifier: string;
     className: string;
     methodName: string;
-}) => `import { defineAction, defineController } from '@generated/server/controller';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineAction, defineController } from '@generated/server/controller';
+
+/*----------------------------------
+- CONTROLEUR
+----------------------------------*/
 
 export default defineController({
     actions: {
@@ -74,11 +90,23 @@ export const createCommandTemplate = ({
 }: {
     className: string;
     methodName: string;
-}) => `import { Commands } from '@server/app/commands';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Commands } from '@server/app/commands';
 import type AppApplication from '@/server/index';
 
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
 type App = InstanceType<typeof AppApplication>;
 
+/*----------------------------------
+- COMMANDS
+----------------------------------*/
+
 export default class ${className} extends Commands<App> {
     public async ${methodName}() {
         return {
@@ -95,7 +123,15 @@ export const createRouteTemplate = ({
 }: {
     httpMethod: string;
     routePath: string;
-}) => `import { defineServerRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineServerRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- ROUTES
+----------------------------------*/
 
 export default defineServerRoute({
     method: ${JSON.stringify(httpMethod.toUpperCase())},
@@ -115,12 +151,24 @@ export const createServiceTemplate = ({
 }: {
     appIdentifier: string;
     className: string;
-}) => `import Service from '@server/app/service';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import Service from '@server/app/service';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
 
 export type Config = {
     debug?: boolean;
 };
 
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+
 export default class ${className} extends Service<Config, {}, ${appIdentifier}, ${appIdentifier}> {
     public async health() {
         return {
@@ -138,9 +186,17 @@ export const createServiceConfigTemplate = ({
     configExportName: string;
     serviceImportPath: string;
     serviceImportName: string;
-}) => `import { Services } from '@server/app';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Services } from '@server/app';
 import ${serviceImportName} from ${JSON.stringify(serviceImportPath)};
 
+/*----------------------------------
+- CONFIG
+----------------------------------*/
+
 export const ${configExportName} = Services.config(${serviceImportName}, {});
 `;
 

package/cli/utils/agents.ts

@@ -1053,11 +1053,11 @@ function renderEmbeddedProjectInstructions({
         '- Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): read Root contract fallback, run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing, run `npx proteum worktree init --source <source-app-root> --refresh` when Proteum reports stale bootstrap state, use `--skip-deps --reason "..."` only for intentional dependency skips, then run `npx proteum runtime status`; for runtime-visible work start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.',
         '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
         '- Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: read `DOCUMENTATION.md` and verify required docs, fix notes, or ADRs were updated or explicitly skipped with a reason.',
-        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`. Run the `CODING_STYLE.md` self-check on the final diff; a non-obvious decision, workaround, or bug fix without a why-comment is a defect to fix before finishing.',
         '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
         '- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: read `DOCUMENTATION.md` before editing and update the relevant fix/regression docs when required.',
         '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
-        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table. While editing, record non-obvious decisions, workarounds, and constraints as why-comments per its `Decision and context comments` section.',
         '',
         '## Routing Table',
         '',