feat: add phase 3 prompt customization backend

- parse prompt model and argument-hint metadata and persist model on prompt invocations
- expand markdown-linked file context in scanned prompt and instruction bodies
- discover .claude/rules instructions and support Claude-style paths metadata
- discover customization roots up to the nearest parent repository and watch them for changes
- apply per-turn prompt model overrides before sidecar execution

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tests/main/appServiceProjectCustomization.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, mock, test } from 'bun:test';
 
 import type { RunTurnCommand } from '@shared/contracts/sidecar';
+import { buildAvailableModelCatalog } from '@shared/domain/models';
 import type { PatternDefinition } from '@shared/domain/pattern';
 import type { ProjectRecord } from '@shared/domain/project';
 import type { SessionRecord } from '@shared/domain/session';
@@ -76,6 +77,7 @@ function createService(
   internals.loadWorkspace = async () => workspace;
   internals.persistAndBroadcast = async (nextWorkspace: WorkspaceState) => nextWorkspace;
   internals.buildEffectivePattern = async () => pattern;
+  internals.loadAvailableModelCatalog = async () => buildAvailableModelCatalog();
   internals.awaitFinalResponseApproval = async () => undefined;
   internals.finalizeTurn = () => undefined;
   internals.emitSessionEvent = () => undefined;
@@ -344,6 +346,84 @@ describe('AryxAppService project customization', () => {
     expect(command?.messages.at(-1)?.content).toBe('Run prompt file: doc-review');
   });
 
+  test('sendSessionMessage hydrates prompt model metadata and overrides the turn pattern model', async () => {
+    const workspace = createWorkspaceSeed();
+    const basePattern = workspace.patterns.find((candidate) => candidate.mode === 'single');
+    if (!basePattern) {
+      throw new Error('Expected a single-agent pattern in the workspace seed.');
+    }
+
+    const pattern: PatternDefinition = {
+      ...basePattern,
+      agents: [
+        {
+          ...basePattern.agents[0]!,
+          model: 'gpt-5.4',
+          reasoningEffort: 'high',
+        },
+      ],
+    };
+
+    const project = createProject({
+      customization: {
+        instructions: [],
+        agentProfiles: [],
+        promptFiles: [
+          {
+            id: 'project_customization_prompt_rest_review',
+            name: 'rest-review',
+            description: 'Review the REST API surface',
+            model: 'Claude Sonnet 4.5',
+            template: 'Review the REST API for security gaps.',
+            variables: [],
+            sourcePath: '.github\\prompts\\rest-review.prompt.md',
+          },
+        ],
+        lastScannedAt: TIMESTAMP,
+      },
+    });
+    const session = createSession(project.id, pattern.id);
+
+    workspace.projects = [project];
+    workspace.sessions = [session];
+    workspace.selectedProjectId = project.id;
+    workspace.selectedPatternId = pattern.id;
+    workspace.selectedSessionId = session.id;
+
+    let command: RunTurnCommand | undefined;
+    const service = createService(workspace, pattern, {
+      captureRunTurn: (capturedCommand) => {
+        command = capturedCommand;
+      },
+    });
+
+    await service.sendSessionMessage(session.id, '', undefined, undefined, {
+      id: 'project_customization_prompt_rest_review',
+      name: 'rest-review',
+      sourcePath: '.github\\prompts\\rest-review.prompt.md',
+      resolvedPrompt: 'Review the REST API for security gaps.',
+    });
+
+    expect(session.messages.at(-1)?.promptInvocation).toEqual({
+      id: 'project_customization_prompt_rest_review',
+      name: 'rest-review',
+      sourcePath: '.github\\prompts\\rest-review.prompt.md',
+      description: 'Review the REST API surface',
+      model: 'Claude Sonnet 4.5',
+      resolvedPrompt: 'Review the REST API for security gaps.',
+    });
+    expect(command?.pattern.agents[0]?.model).toBe('claude-sonnet-4.5');
+    expect(command?.pattern.agents[0]?.reasoningEffort).toBeUndefined();
+    expect(command?.promptInvocation).toEqual({
+      id: 'project_customization_prompt_rest_review',
+      name: 'rest-review',
+      sourcePath: '.github\\prompts\\rest-review.prompt.md',
+      description: 'Review the REST API surface',
+      model: 'Claude Sonnet 4.5',
+      resolvedPrompt: 'Review the REST API for security gaps.',
+    });
+  });
+
   test('setProjectAgentProfileEnabled persists the updated enabled state', async () => {
     const workspace = createWorkspaceSeed();
     const pattern = workspace.patterns.find((candidate) => candidate.mode === 'single');

tests/main/customizationScanner.test.ts

@@ -22,7 +22,7 @@ async function createTempDirectory(): Promise<string> {
 describe('ProjectCustomizationScanner', () => {
   test('discovers recursive instruction, agent, and prompt files with metadata', async () => {
     const projectPath = await createTempDirectory();
-    await mkdir(join(projectPath, '.claude'), { recursive: true });
+    await mkdir(join(projectPath, '.claude', 'rules'), { recursive: true });
     await mkdir(join(projectPath, '.github', 'agents', 'docs'), { recursive: true });
     await mkdir(join(projectPath, '.github', 'instructions', 'frontend'), { recursive: true });
     await mkdir(join(projectPath, '.github', 'instructions', 'tasks'), { recursive: true });
@@ -48,6 +48,19 @@ Use TypeScript.
       '# Claude guidance\nPrefer cohesive designs.\n',
       'utf8',
     );
+    await writeFile(
+      join(projectPath, '.claude', 'rules', 'typescript.md'),
+      `---
+name: Claude TypeScript Rules
+description: Claude-format TypeScript rules
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+Always use strict TypeScript settings.
+`,
+      'utf8',
+    );
     await writeFile(
       join(projectPath, '.github', 'instructions', 'frontend', 'react.instructions.md'),
       `---
@@ -55,10 +68,17 @@ name: React Standards
 description: React file conventions
 applyTo: "**/*.tsx"
 ---
+Apply the [shared standards](./shared-standards.md).
+
 Use hooks and keep components focused.
 `,
       'utf8',
     );
+    await writeFile(
+      join(projectPath, '.github', 'instructions', 'frontend', 'shared-standards.md'),
+      '# Shared Standards\nPrefer explicit props and accessible interactions.\n',
+      'utf8',
+    );
     await writeFile(
       join(projectPath, '.github', 'instructions', 'tasks', 'planning.instructions.md'),
       `---
@@ -98,6 +118,8 @@ Focus on repository documentation only.
       `---
 name: explain-selected-code
 agent: agent
+model: Claude Sonnet 4.5
+argument-hint: Paste code or describe the area you want explained
 description: Generate a clear explanation
 tools:
   - view
@@ -106,9 +128,16 @@ tools:
 Explain the following code:
 \${input:code:Paste your code here}
 Audience: \${input:audience:Who is this for?}
+
+Follow the [shared explanation rubric](./explanation-rubric.md)
 `,
       'utf8',
     );
+    await writeFile(
+      join(projectPath, '.github', 'prompts', 'docs', 'explanation-rubric.md'),
+      '# Explanation rubric\n- Start with a summary.\n- Call out edge cases.\n',
+      'utf8',
+    );
 
     const scanned = await new ProjectCustomizationScanner().scanProject(projectPath);
 
@@ -119,6 +148,15 @@ Audience: \${input:audience:Who is this for?}
         content: '# Claude guidance\nPrefer cohesive designs.',
         applicationMode: 'always',
       },
+      {
+        id: expect.any(String),
+        sourcePath: '.claude\\rules\\typescript.md',
+        name: 'Claude TypeScript Rules',
+        description: 'Claude-format TypeScript rules',
+        applyTo: 'src/**/*.ts,src/**/*.tsx',
+        content: 'Always use strict TypeScript settings.',
+        applicationMode: 'file',
+      },
       {
         id: expect.any(String),
         sourcePath: '.github\\copilot-instructions.md',
@@ -132,7 +170,13 @@ Audience: \${input:audience:Who is this for?}
         name: 'React Standards',
         description: 'React file conventions',
         applyTo: '**/*.tsx',
-        content: 'Use hooks and keep components focused.',
+        content:
+          'Apply the [shared standards](./shared-standards.md).\n\n'
+          + 'Use hooks and keep components focused.\n\n'
+          + 'Referenced file context:\n\n'
+          + 'Source: .github\\instructions\\frontend\\shared-standards.md\n'
+          + 'Contents:\n'
+          + '# Shared Standards\nPrefer explicit props and accessible interactions.',
         applicationMode: 'file',
       },
       {
@@ -179,9 +223,19 @@ Audience: \${input:audience:Who is this for?}
         id: expect.any(String),
         name: 'explain-selected-code',
         description: 'Generate a clear explanation',
+        argumentHint: 'Paste code or describe the area you want explained',
         agent: 'agent',
+        model: 'Claude Sonnet 4.5',
         tools: ['view', 'glob'],
-        template: 'Explain the following code:\n${input:code:Paste your code here}\nAudience: ${input:audience:Who is this for?}',
+        template:
+          'Explain the following code:\n'
+          + '${input:code:Paste your code here}\n'
+          + 'Audience: ${input:audience:Who is this for?}\n\n'
+          + 'Follow the [shared explanation rubric](./explanation-rubric.md)\n\n'
+          + 'Referenced file context:\n\n'
+          + 'Source: .github\\prompts\\docs\\explanation-rubric.md\n'
+          + 'Contents:\n'
+          + '# Explanation rubric\n- Start with a summary.\n- Call out edge cases.',
         variables: [
           { name: 'code', placeholder: 'Paste your code here' },
           { name: 'audience', placeholder: 'Who is this for?' },
@@ -192,6 +246,64 @@ Audience: \${input:audience:Who is this for?}
     expect(scanned.lastScannedAt).toEqual(expect.any(String));
   });
 
+  test('discovers customization files from parent repository roots', async () => {
+    const repoRoot = await createTempDirectory();
+    const projectPath = join(repoRoot, 'packages', 'frontend');
+    await mkdir(join(repoRoot, '.git'), { recursive: true });
+    await mkdir(join(projectPath, 'src'), { recursive: true });
+    await mkdir(join(repoRoot, '.github', 'prompts'), { recursive: true });
+    await mkdir(join(repoRoot, '.claude', 'rules'), { recursive: true });
+    await mkdir(join(repoRoot, 'docs'), { recursive: true });
+
+    await writeFile(
+      join(repoRoot, '.github', 'prompts', 'repo-review.prompt.md'),
+      `---
+name: repo-review
+model: GPT-5.4
+---
+Review the repo using the [checklist](../../docs/review-checklist.md).
+`,
+      'utf8',
+    );
+    await writeFile(
+      join(repoRoot, '.claude', 'rules', 'global.md'),
+      'Use the monorepo release process.',
+      'utf8',
+    );
+    await writeFile(
+      join(repoRoot, 'docs', 'review-checklist.md'),
+      '# Checklist\n- Confirm changelog updates.\n- Check release notes.\n',
+      'utf8',
+    );
+
+    const scanned = await new ProjectCustomizationScanner().scanProject(projectPath);
+
+    expect(scanned.instructions).toEqual([
+      {
+        id: expect.any(String),
+        sourcePath: '..\\..\\.claude\\rules\\global.md',
+        applyTo: '**',
+        content: 'Use the monorepo release process.',
+        applicationMode: 'always',
+      },
+    ]);
+    expect(scanned.promptFiles).toEqual([
+      {
+        id: expect.any(String),
+        name: 'repo-review',
+        model: 'GPT-5.4',
+        template:
+          'Review the repo using the [checklist](../../docs/review-checklist.md).\n\n'
+          + 'Referenced file context:\n\n'
+          + 'Source: ..\\..\\docs\\review-checklist.md\n'
+          + 'Contents:\n'
+          + '# Checklist\n- Confirm changelog updates.\n- Check release notes.',
+        variables: [],
+        sourcePath: '..\\..\\.github\\prompts\\repo-review.prompt.md',
+      },
+    ]);
+  });
+
   test('retains the previous parsed agent profile when frontmatter becomes malformed', async () => {
     const projectPath = await createTempDirectory();
     await mkdir(join(projectPath, '.github', 'agents'), { recursive: true });

tests/main/projectCustomizationWatcher.test.ts

@@ -38,6 +38,25 @@ describe('ProjectCustomizationWatcher', () => {
     ]);
   });
 
+  test('includes parent repository roots when the project is nested inside a monorepo', async () => {
+    const repoRoot = await createTempDirectory();
+    const projectPath = join(repoRoot, 'packages', 'frontend');
+    await mkdir(join(repoRoot, '.git'), { recursive: true });
+    await mkdir(join(projectPath, 'src'), { recursive: true });
+    await mkdir(join(repoRoot, '.github', 'prompts'), { recursive: true });
+    await mkdir(join(repoRoot, '.claude', 'rules'), { recursive: true });
+
+    expect(await collectProjectCustomizationWatchPaths(projectPath)).toEqual([
+      join(repoRoot, '.claude'),
+      join(repoRoot, '.claude', 'rules'),
+      join(repoRoot, '.github'),
+      join(repoRoot, '.github', 'prompts'),
+      join(repoRoot, 'packages'),
+      projectPath,
+      repoRoot,
+    ].sort((left, right) => left.localeCompare(right)));
+  });
+
   test('debounces change notifications and closes watches when projects are removed', async () => {
     const changeCalls: string[] = [];
     const closeByPath = new Map<string, ReturnType<typeof mock>>();

tests/shared/models.test.ts

@@ -4,6 +4,7 @@ import type { SidecarModelCapability } from '@shared/contracts/sidecar';
 import {
   buildAvailableModelCatalog,
   findModel,
+  findModelByReference,
   normalizePatternModels,
   resolveReasoningEffort,
 } from '@shared/domain/models';
@@ -62,6 +63,13 @@ describe('dynamic model catalog', () => {
     expect(resolveReasoningEffort(model, 'high')).toBeUndefined();
   });
 
+  test('resolves model references by id or display name', () => {
+    const catalog = buildAvailableModelCatalog(availableModels);
+
+    expect(findModelByReference('gpt-5.4', catalog)?.id).toBe('gpt-5.4');
+    expect(findModelByReference('Claude Sonnet 4.5', catalog)?.id).toBe('claude-sonnet-4.5');
+  });
+
   test('normalizes pattern agents before runtime execution', () => {
     const normalized = normalizePatternModels(
       createPattern(),

tests/shared/sessionLibrary.test.ts

@@ -161,6 +161,7 @@ describe('session library helpers', () => {
             name: 'doc-review',
             sourcePath: '.github\\prompts\\docs\\doc-review.prompt.md',
             resolvedPrompt: 'Review the docs for missing steps.',
+            model: 'Claude Sonnet 4.5',
             tools: ['view'],
           },
         },
@@ -189,6 +190,7 @@ describe('session library helpers', () => {
       name: 'doc-review',
       sourcePath: '.github\\prompts\\docs\\doc-review.prompt.md',
       resolvedPrompt: 'Review the docs for missing steps.',
+      model: 'Claude Sonnet 4.5',
       tools: ['view'],
     });
     expect(session.messages[0]?.promptInvocation).not.toBe(sourceSession.messages[0]?.promptInvocation);
@@ -508,6 +510,7 @@ describe('session library helpers', () => {
             name: 'alt-plan',
             sourcePath: '.github\\prompts\\alt-plan.prompt.md',
             resolvedPrompt: 'Try a different approach focused on session state.',
+            model: 'GPT-5.4',
             tools: ['view', 'glob'],
           },
           attachments: [