proteum 2.4.4 → 2.5.1

package/server/app/controller/index.ts

@@ -5,8 +5,6 @@
 // Npm
 import zod from 'zod';
 
-// Core
-import context from '@server/context';
 import {
     toValidationSchema,
     type TValidationSchema,
@@ -63,11 +61,6 @@ export type TControllerRequestContext<
 } & (TRouter extends TAnyRouter ? TRouterContextServices<TControllerRouter<TRouter>> : {}) &
     TRequestServices;
 
-type TControllerBaseContext<TApplication extends object> = {
-    app: TApplication;
-    request: { data: TObjetDonnees };
-};
-
 type TControllerDefaultContext<TApplication extends object, TRequestServices extends object> = {
     app: TApplication;
     context: object;
@@ -80,43 +73,108 @@ type TControllerDefaultContext<TApplication extends object, TRequestServices ext
 } & TRouterContextServices<TControllerApplicationRouter<TApplication>> &
     TRequestServices;
 
-/*----------------------------------
-- CLASS
-----------------------------------*/
-
-export default abstract class Controller<
+export type TControllerActionContext<
+    TInput = undefined,
     TApplication extends object = object,
-    TRouter extends object = object,
     TRequestServices extends object = {},
-    TContext extends TControllerBaseContext<TApplication> = TControllerDefaultContext<TApplication, TRequestServices>,
-> {
-    public constructor(public request: TContext) {}
-
-    public get app(): TApplication {
-        return this.request.app as TApplication;
-    }
-
-    public get services(): TApplication {
-        return this.app;
-    }
-
-    public get models(): TControllerModelsClient<TApplication> {
-        const app = this.app as {
-            models?: { client?: TControllerModelsClient<TApplication> };
-            Models?: { client?: TControllerModelsClient<TApplication> };
-        };
-        return (app.models?.client ?? app.Models?.client) as TControllerModelsClient<TApplication>;
-    }
+> = TControllerDefaultContext<TApplication, TRequestServices> & {
+    input: TInput;
+    models: TControllerModelsClient<TApplication>;
+    services: TApplication;
+};
 
-    public input<TSchema extends TValidationSchema>(schema: TSchema): zod.output<TSchema>;
-    public input<TShape extends TValidationShape>(schema: TShape): zod.output<zod.ZodObject<TShape>>;
-    public input(schema: TValidationSchema | TValidationShape) {
-        const store = context.getStore() as { inputSchemaUsed?: boolean } | undefined;
+export type TControllerActionDefinition<
+    TInput = undefined,
+    TResult = unknown,
+    TApplication extends object = object,
+    TRequestServices extends object = {},
+> = {
+    input?: TValidationSchema | TValidationShape;
+    handler: (context: TControllerActionContext<TInput, TApplication, TRequestServices>) => TResult;
+};
 
-        if (store?.inputSchemaUsed) throw new Error('Controller.input() can only be called once per request handler.');
+export type TControllerDefinition<
+    TActions extends Record<string, TControllerActionDefinition<any, any, any, any>>,
+> = {
+    kind: 'controller';
+    path?: string;
+    actions: TActions;
+};
 
-        if (store) store.inputSchemaUsed = true;
+export type TControllerActionInput<TController, TMethod extends keyof any> = TController extends { actions: infer TActions }
+    ? TMethod extends keyof TActions
+        ? TActions[TMethod] extends TControllerActionDefinition<infer TInput, any, any, any>
+            ? TInput
+            : never
+        : never
+    : never;
 
-        return toValidationSchema(schema).parse(this.request.request.data);
-    }
+export type TControllerActionResult<TController, TMethod extends keyof any> = TController extends {
+    actions: infer TActions;
+}
+    ? TMethod extends keyof TActions
+        ? TActions[TMethod] extends TControllerActionDefinition<any, infer TResult, any, any>
+            ? Awaited<TResult>
+            : never
+        : never
+    : never;
+
+export function defineAction<TSchema extends TValidationSchema, TResult>(
+    definition: {
+        input: TSchema;
+        handler: (context: TControllerActionContext<zod.output<TSchema>>) => TResult;
+    },
+): TControllerActionDefinition<zod.output<TSchema>, TResult>;
+export function defineAction<TShape extends TValidationShape, TResult>(
+    definition: {
+        input: TShape;
+        handler: (context: TControllerActionContext<zod.output<zod.ZodObject<TShape>>>) => TResult;
+    },
+): TControllerActionDefinition<zod.output<zod.ZodObject<TShape>>, TResult>;
+export function defineAction<TResult>(
+    definition: {
+        handler: (context: TControllerActionContext<undefined>) => TResult;
+    },
+): TControllerActionDefinition<undefined, TResult>;
+export function defineAction(definition: {
+    input?: TValidationSchema | TValidationShape;
+    handler: (context: TControllerActionContext<any>) => unknown;
+}) {
+    return definition;
 }
+
+export const defineController = <
+    TActions extends Record<string, TControllerActionDefinition<any, any, any, any>>,
+>({
+    path,
+    actions,
+}: {
+    path?: string;
+    actions: TActions;
+}): TControllerDefinition<TActions> => ({
+    kind: 'controller',
+    path,
+    actions,
+});
+
+export const runControllerAction = (
+    action: TControllerActionDefinition<any, any, any, any>,
+    requestContext: TControllerDefaultContext<any, any>,
+) => {
+    const input = action.input === undefined ? undefined : toValidationSchema(action.input).parse(requestContext.request.data);
+    const app = requestContext.app as {
+        models?: { client?: object };
+        Models?: { client?: object };
+    };
+    const appRecord = app as Record<string, unknown>;
+    const explicitModels = Object.prototype.hasOwnProperty.call(appRecord, 'models')
+        ? (appRecord.models as { client?: object } | undefined)
+        : undefined;
+
+    return action.handler({
+        ...requestContext,
+        input,
+        models: explicitModels?.client ?? app.Models?.client ?? {},
+        services: requestContext.app,
+    });
+};

package/server/app/index.ts

@@ -40,6 +40,33 @@ export type TApplicationStartOptions = {
 
 export const Service = ServicesContainer;
 
+type TApplicationDefinitionValue<TValue, TApplication extends object> =
+    | TValue
+    | ((app: TApplication) => TValue);
+
+type TDefinedApplicationContext<
+    TServices extends Record<string, unknown>,
+    TRouter,
+    TModels = unknown,
+> = Application &
+    TServices & {
+        Router: TRouter;
+        models?: TModels;
+        Models?: TModels;
+    };
+
+export type TApplicationDefinition<
+    TServices extends Record<string, unknown> = {},
+    TRouter = unknown,
+    TModels = unknown,
+    TCommands = unknown,
+> = {
+    services?: TApplicationDefinitionValue<TServices, TDefinedApplicationContext<TServices, TRouter>>;
+    router?: TApplicationDefinitionValue<TRouter, TDefinedApplicationContext<TServices, TRouter>>;
+    models?: TApplicationDefinitionValue<TModels, TDefinedApplicationContext<TServices, TRouter>>;
+    commands?: TApplicationDefinitionValue<TCommands, TDefinedApplicationContext<TServices, TRouter, TModels>>;
+};
+
 // Without prettify, we don't get a clear list of the class properties
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
@@ -65,6 +92,24 @@ const createCommandsManager = (app: Application) => new CommandsManager(app, { d
 const createDevCommandsRegistry = (app: Application) => new DevCommandsRegistry(app);
 const createDevDiagnosticsRegistry = (app: Application) => new DevDiagnosticsRegistry(app);
 
+const normalizeReportedError = (rejection: unknown, fallbackMessage: string): Error => {
+    if (rejection instanceof Error) return rejection;
+    if (typeof rejection === 'string') return new Error(rejection);
+
+    return new Error(fallbackMessage);
+};
+
+const getNumericErrorProperty = (error: Error, property: 'http' | 'status' | 'statusCode') => {
+    const value = (error as Error & Partial<Record<typeof property, unknown>>)[property];
+    return typeof value === 'number' ? value : undefined;
+};
+
+const getErrorHttpCode = (error: Error) =>
+    getNumericErrorProperty(error, 'http') ??
+    getNumericErrorProperty(error, 'status') ??
+    getNumericErrorProperty(error, 'statusCode') ??
+    500;
+
 /*----------------------------------
 - FUNCTIONS
 ----------------------------------*/
@@ -78,7 +123,7 @@ export abstract class Application<
     public app!: this;
     public servicesContainer!: TServicesContainer;
     public userType!: TUser;
-    public declare Router: object;
+    public declare Router: unknown;
 
     /*----------------------------------
     - PROPERTIES
@@ -111,12 +156,12 @@ export abstract class Application<
         // Handle unhandled crash
         this.on('error', (e, request) => this.container.handleBug(e, 'An error occured in the application', request));
 
-        process.on('unhandledRejection', (error: any, _promise: any) => {
+        process.on('unhandledRejection', (error: unknown) => {
             // Log so we know it's coming from unhandledRejection
             console.error('unhandledRejection', error);
 
             // We don't log the error here because it's the role of the app to decidehiw to log errors
-            this.runHook('error', error);
+            void this.reportError(error);
         });
 
         // We can't pass this in super so we assign here
@@ -128,6 +173,14 @@ export abstract class Application<
         return this.container.Console.createBugReport(new Anomaly(...anomalyArgs));
     }
 
+    public async reportError(rejection: unknown, request?: ServerRequest<TServerRouter>) {
+        const error = normalizeReportedError(rejection, 'Unknown application error');
+        const code = getErrorHttpCode(error);
+
+        if (code === 500) await this.runHook('error', error, request);
+        else await this.runHook('error.' + code, error, request);
+    }
+
     /*----------------------------------
     - COMMANDS
     ----------------------------------*/
@@ -268,4 +321,68 @@ export abstract class Application<
     }
 }
 
+const resolveApplicationDefinitionValue = <TValue, TApplication extends object>(
+    value: TApplicationDefinitionValue<TValue, TApplication> | undefined,
+    app: TApplication,
+): TValue | undefined => (typeof value === 'function' ? (value as (app: TApplication) => TValue)(app) : value);
+
+const assignApplicationRecord = (target: object, value: unknown) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+
+    Object.assign(target, value);
+};
+
+export const defineApplication = <
+    TServices extends Record<string, unknown> = {},
+    TRouter = unknown,
+    TModels = unknown,
+    TCommands = unknown,
+>(
+    definition: TApplicationDefinition<TServices, TRouter, TModels, TCommands>,
+) => {
+    type TDefinedApplication = Application &
+        TServices & {
+            Router: TRouter;
+            models?: TModels;
+            Models?: TModels;
+            commands?: TCommands;
+        };
+
+    class DefinedApplication extends Application {
+        public constructor() {
+            super();
+
+            const self = this as unknown as TDefinedApplication & Record<string, unknown>;
+            const services = resolveApplicationDefinitionValue(
+                definition.services,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            assignApplicationRecord(self, services);
+
+            const router = resolveApplicationDefinitionValue(
+                definition.router,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            if (router !== undefined) (self as Record<string, unknown>).Router = router;
+
+            const models = resolveApplicationDefinitionValue(
+                definition.models,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            if (models !== undefined) {
+                (self as Record<string, unknown>).models = models;
+                (self as Record<string, unknown>).Models = models;
+            }
+
+            const commands = resolveApplicationDefinitionValue(
+                definition.commands,
+                self as TDefinedApplicationContext<TServices, TRouter, TModels>,
+            );
+            if (commands !== undefined) (self as Record<string, unknown>).commands = commands;
+        }
+    }
+
+    return DefinedApplication as unknown as new () => TDefinedApplication;
+};
+
 export default Application;

package/server/app/service/index.ts

@@ -145,7 +145,11 @@ export default abstract class Service<
             models?: { client?: TServiceModelsClient<TApplication> };
             Models?: { client?: TServiceModelsClient<TApplication> };
         };
-        const models = app.models?.client ?? app.Models?.client;
+        const appRecord = app as Record<string, unknown>;
+        const explicitModels = Object.prototype.hasOwnProperty.call(appRecord, 'models')
+            ? (appRecord.models as { client?: TServiceModelsClient<TApplication> } | undefined)
+            : undefined;
+        const models = explicitModels?.client ?? app.Models?.client;
 
         if (!models)
             throw new Error(`${this.constructor.name} tried to access models but no Models service is registered.`);

package/server/index.ts

@@ -3,6 +3,10 @@ import Application from '@/server/index';
 import { isServerHotReloadRequest, serverHotReloadMessageType } from '@common/dev/serverHotReload';
 
 const application = AppContainer.start(Application);
+const router = application.Router as {
+    started?: Promise<unknown>;
+    reloadGeneratedDefinitions?: (changedFiles: string[]) => Promise<unknown>;
+};
 let shutdownPromise: Promise<void> | undefined;
 
 const shutdownApplication = async (reason: string) => {
@@ -36,8 +40,8 @@ if (__DEV__ && typeof process.send === 'function') {
 
         void (async () => {
             try {
-                await application.Router?.started;
-                await application.Router.reloadGeneratedDefinitions(message.changedFiles);
+                await router.started;
+                await router.reloadGeneratedDefinitions?.(message.changedFiles);
 
                 process.send?.({ type: serverHotReloadMessageType.succeeded, changedFiles: message.changedFiles });
             } catch (error) {

package/server/services/router/index.ts

@@ -14,12 +14,12 @@ const { v4: uuid } = require('uuid') as { v4: () => string };
 import got from 'got';
 import hInterval from 'human-interval';
 import type express from 'express';
-import type { Request, Response, NextFunction } from 'express';
 import zod, { ZodError } from 'zod';
 export { default as schema } from 'zod';
 
 // Core
 import type { Application } from '@server/app/index';
+import { runControllerAction, type TControllerActionDefinition } from '@server/app/controller';
 import Service, { TServiceArgs } from '@server/app/service';
 import context from '@server/context';
 import type DisksManager from '@server/services/disks';
@@ -30,9 +30,12 @@ import BaseRouter, {
     TErrorRoute,
     TRouteModule,
     TRouteOptions,
+    type TRouteDefinition,
+    type TRouteMetadata,
     defaultOptions,
     matchRoute,
     buildUrl,
+    withRouteMetadata,
 } from '@common/router';
 import type { TSsrUnresolvedRoute, TRegisterPageArgs } from '@common/router/contracts';
 import { buildRegex, getRegisterPageArgs } from '@common/router/register';
@@ -76,7 +79,7 @@ type TGeneratedControllerDefinition = {
     path: string;
     filepath: string;
     sourceLocation: { line: number; column: number };
-    Controller: new (request: TRouterContext<TServerRouter>) => { [method: string]: () => any };
+    action: TControllerActionDefinition<any, any, any, any>;
     method: string;
 };
 
@@ -385,7 +388,7 @@ export default class ServerRouter<
             }
         }
 
-        this.afterRegister();
+        this.refreshRouteRegistration();
     }
 
     private registerControllers(definitions: TGeneratedControllerDefinition[]) {
@@ -393,10 +396,8 @@ export default class ServerRouter<
             const route: TRoute<TRouterContext<this>> = {
                 method: 'POST',
                 path: definition.path,
-                controller: (requestContext: TRouterContext<this>) => {
-                    const controller = new definition.Controller(requestContext);
-                    return controller[definition.method]();
-                },
+                controller: (requestContext: TRouterContext<this>) =>
+                    runControllerAction(definition.action, requestContext as any),
                 options: { ...defaultOptions, filepath: definition.filepath, sourceLocation: definition.sourceLocation },
             };
 
@@ -419,7 +420,31 @@ export default class ServerRouter<
     - REGISTER
     ----------------------------------*/
 
-    public page(...args: TRegisterPageArgs<any, TRouteOptions>) {
+    public registerRouteDefinition(definition: TRouteDefinition, metadata: TRouteMetadata = {}) {
+        if (definition.kind === 'page') {
+            return this.page(
+                definition.path,
+                withRouteMetadata(definition.options, metadata),
+                definition.data,
+                definition.render,
+            );
+        }
+
+        if (definition.kind === 'error') {
+            return this.error(definition.code, withRouteMetadata(definition.options, metadata), definition.render);
+        }
+
+        const method = definition.method === '*' ? '*' : (definition.method.toUpperCase() as TRouteHttpMethod);
+
+        return this.registerApi(
+            method,
+            definition.path,
+            withRouteMetadata(definition.options, metadata),
+            definition.handler as TServerController<this>,
+        );
+    }
+
+    protected page(...args: TRegisterPageArgs<any, TRouteOptions>) {
         const { path, options, data, renderer, layout } = getRegisterPageArgs(...args);
 
         const { regex, keys } = buildRegex(path);
@@ -442,7 +467,7 @@ export default class ServerRouter<
         return this;
     }
 
-    public error(
+    protected error(
         code: number,
         options: Partial<TRouteOptions>,
         renderer: TFrontRenderer<{}, { message: string }>,
@@ -461,34 +486,13 @@ export default class ServerRouter<
         this.errors[code] = route;
     }
 
-    public all = (...args: TApiRegisterArgs<this>) => this.registerApi('*', ...args);
-    public options = (...args: TApiRegisterArgs<this>) => this.registerApi('OPTIONS', ...args);
-    public get = (...args: TApiRegisterArgs<this>) => this.registerApi('GET', ...args);
-    public post = (...args: TApiRegisterArgs<this>) => this.registerApi('POST', ...args);
-    public put = (...args: TApiRegisterArgs<this>) => this.registerApi('PUT', ...args);
-    public patch = (...args: TApiRegisterArgs<this>) => this.registerApi('PATCH', ...args);
-    public delete = (...args: TApiRegisterArgs<this>) => this.registerApi('DELETE', ...args);
-
-    public express(
-        middleware: (req: Request, res: Response, next: NextFunction, requestContext: TRouterContext<this>) => void,
-    ) {
-        return (context: TRouterContext<this>) =>
-            new Promise((resolve) => {
-                context.request.res.on('finish', function () {
-                    //console.log('the response has been sent', request.res.statusCode);
-                    resolve(true);
-                });
-
-                middleware(
-                    context.request.req,
-                    context.request.res,
-                    () => {
-                        resolve(true);
-                    },
-                    context,
-                );
-            });
-    }
+    protected all = (...args: TApiRegisterArgs<this>) => this.registerApi('*', ...args);
+    protected options = (...args: TApiRegisterArgs<this>) => this.registerApi('OPTIONS', ...args);
+    protected get = (...args: TApiRegisterArgs<this>) => this.registerApi('GET', ...args);
+    protected post = (...args: TApiRegisterArgs<this>) => this.registerApi('POST', ...args);
+    protected put = (...args: TApiRegisterArgs<this>) => this.registerApi('PUT', ...args);
+    protected patch = (...args: TApiRegisterArgs<this>) => this.registerApi('PATCH', ...args);
+    protected delete = (...args: TApiRegisterArgs<this>) => this.registerApi('DELETE', ...args);
 
     protected registerApi(method: TRouteHttpMethod, ...args: TApiRegisterArgs<this>): this {
         let path: string;
@@ -565,7 +569,11 @@ export default class ServerRouter<
         );
     }
 
-    private async afterRegister() {
+    public refreshRouteRegistration() {
+        this.afterRegister();
+    }
+
+    private afterRegister() {
         // Ordonne par ordre de priorité
         this.config.debug && console.info('Loading routes ...');
         this.routes.sort((r1, r2) => {
@@ -579,6 +587,7 @@ export default class ServerRouter<
             return 0;
         });
         // - Génère les définitions de route pour le client
+        this.ssrRoutes = [];
         this.config.debug && console.info(`Registered routes:`);
         for (const route of this.routes) {
             const chunkId = route.options.id;
@@ -628,7 +637,7 @@ export default class ServerRouter<
                 error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown request.finished hook error');
 
             try {
-                await this.app.runHook('error', typedError, request);
+                await this.app.reportError(typedError, request);
             } catch (hookError) {
                 console.error('request.finished hook error', typedError, 'Error hook failure', hookError);
             }
@@ -1102,7 +1111,7 @@ export default class ServerRouter<
             console.log(LogPrefix, 'Error catched from the router:', error);
 
             // Report error
-            await this.app.runHook('error', error, request);
+            await this.app.reportError(error, request);
 
             // Don't exose technical errors to users
             if (this.app.env.profile === 'prod')
@@ -1114,7 +1123,7 @@ export default class ServerRouter<
             /*if (this.app.env.profile === "dev")
                 console.warn(e);*/
 
-            await this.app.runHook('error.' + code, error, request);
+            await this.app.reportError(error, request);
         }
 
         // Return error based on the request format

package/server/services/router/response/index.ts

@@ -60,6 +60,7 @@ export type TRouterContext<TRouter extends TServerRouter> =
     // Request context
     {
         app: TServerRouterApplication<TRouter>;
+        services: TServerRouterApplication<TRouter>;
         context: TRouterContext<TRouter>; // = this
         request: ServerRequest<TRouter>;
         api: ServerRequest<TRouter>['api'];
@@ -155,14 +156,12 @@ export default class ServerResponse<
         const contextStore = context.getStore() as
             | {
                   requestContext?: TRouterContext<TAnyRouter>;
-                  inputSchemaUsed?: boolean;
                   ownerLabel?: string;
                   ownerFilepath?: string;
               }
             | undefined;
         if (contextStore) {
             contextStore.requestContext = requestContext;
-            contextStore.inputSchemaUsed = false;
             contextStore.ownerLabel = getRouteTraceTarget(route as TAnyRoute<TRouterContext<TServerRouter>>);
             contextStore.ownerFilepath = route.options.filepath || undefined;
         }
@@ -229,6 +228,7 @@ export default class ServerResponse<
         const requestContext: TRouterContext<TRouter> = {
             // Router context
             app: this.app,
+            services: this.app,
             context: undefined!,
             request: this.request,
             response: this,

package/tests/agents-utils.test.cjs

@@ -104,11 +104,23 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.match(agentsContent, /\/__proteum\/mcp/);
     assert.match(agentsContent, /central MCP ready banner/);
     assert.match(agentsContent, /proteum-mcp-v1/);
+    assert.match(agentsContent, /## Explicit App-Building Contract/);
+    assert.match(agentsContent, /defineApplication\(\{ services, router, models, commands \}\)/);
+    assert.match(agentsContent, /definePageRoute\(\{ path, options, data, render \}\)/);
+    assert.match(agentsContent, /defineController\(\{ path, actions \}\)/);
+    assert.match(agentsContent, /Never import `@app` in page, route, or controller files/);
+    assert.match(agentsContent, /Never call top-level `Router\.page\(\.\.\.\)`/);
     assert.match(agentsContent, /## Triggered Instruction Reads/);
+    assert.match(agentsContent, /Worktree Preflight/);
+    assert.match(agentsContent, /npx proteum worktree init --source <source-app-root>/);
+    assert.match(agentsContent, /--skip-deps --reason/);
     assert.match(agentsContent, /Git lifecycle/);
     assert.match(agentsContent, /read Root contract fallback before any git write/);
+    assert.match(agentsContent, /Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change/);
     assert.match(agentsContent, /add or update focused unit tests/);
-    assert.match(agentsContent, /read Root contract fallback, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /read Root contract fallback, `DOCUMENTATION\.md`, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /Bug fixes, regressions, incidents, broken public routes, auth\/OAuth failures/);
+    assert.match(agentsContent, /docs\/fixes\/YYYY-MM-DD-short-bug-name\.md/);
     assert.match(agentsContent, /GEO\/SEO\/crawler\/structured-data\/AI-source changes/);
     assert.match(agentsContent, /MCP-selected previews are enough/);
     assert.doesNotMatch(agentsContent, /Conventional Commits/);
@@ -234,6 +246,7 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Known Proteum Apps/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /apps\/product/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Do not start `npx proteum dev` from this root/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Worktree Preflight/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'DOCUMENTATION.md'), 'utf8'), /## Source: DOCUMENTATION\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'diagnostics.md'), 'utf8'), /## Source: diagnostics\.md/);