proteum 2.2.8 → 2.3.0

package/cli/utils/agents.ts

@@ -23,12 +23,14 @@ type TConfigureProjectAgentInstructionsArgs = {
 type TAgentInstructionDefinition = {
     projectPath: string;
     ensureParentDir?: boolean;
+    content?: 'router' | 'source';
 };
 
 type TEnsureInstructionFilesResult = {
     blocked: string[];
     created: string[];
     overwritten: string[];
+    removed: string[];
     skipped: string[];
     updated: string[];
 };
@@ -40,6 +42,7 @@ export type TConfigureProjectAgentInstructionsResult = {
     monorepoRoot?: string;
     mode: 'monorepo' | 'standalone';
     overwritten: string[];
+    removed: string[];
     skipped: string[];
     updated: string[];
     updatedGitignores: string[];
@@ -57,29 +60,40 @@ const managedInstructionSectionStart = '<!-- proteum-instructions:start -->';
 const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
 
-const sharedAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'CODING_STYLE.md' },
-    { projectPath: 'diagnostics.md' },
-    { projectPath: 'optimizations.md' },
-    { projectPath: path.join('client', 'AGENTS.md') },
-    { projectPath: path.join('client', 'pages', 'AGENTS.md') },
-    { projectPath: path.join('server', 'services', 'AGENTS.md') },
-    { projectPath: path.join('server', 'routes', 'AGENTS.md') },
-    { projectPath: path.join('tests', 'e2e', 'AGENTS.md') },
+const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: 'CODING_STYLE.md', content: 'source' },
+    { projectPath: 'diagnostics.md', content: 'source' },
+    { projectPath: 'optimizations.md', content: 'source' },
+];
+
+const sharedAppAreaAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('client', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('client', 'pages', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('server', 'services', 'AGENTS.md'), content: 'source' },
+    { projectPath: path.join('server', 'routes', 'AGENTS.md'), content: 'source' },
+];
+
+const sharedE2eAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), ensureParentDir: true, content: 'source' },
+    { projectPath: path.join('tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), ensureParentDir: true, content: 'source' },
 ];
 
 const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
-    ...sharedAppAgentInstructionDefinitions,
+    { projectPath: 'AGENTS.md', content: 'router' },
+    ...sharedRootDocumentInstructionDefinitions,
+    ...sharedAppAreaAgentInstructionDefinitions,
+    ...sharedE2eAgentInstructionDefinitions,
 ];
 
 const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
-    ...sharedAppAgentInstructionDefinitions,
+    { projectPath: 'AGENTS.md', content: 'router' },
+    ...sharedAppAreaAgentInstructionDefinitions,
 ];
 
 const monorepoRootAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
-    { projectPath: 'AGENTS.md' },
+    { projectPath: 'AGENTS.md', content: 'router' },
+    ...sharedRootDocumentInstructionDefinitions,
+    ...sharedE2eAgentInstructionDefinitions,
 ];
 
 const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
@@ -111,6 +125,7 @@ export function configureProjectAgentInstructions({
         created: [],
         mode,
         overwritten: [],
+        removed: [],
         skipped: [],
         updated: [],
         updatedGitignores: [],
@@ -152,7 +167,31 @@ export function configureProjectAgentInstructions({
     );
     mergeInstructionResults(result, appFiles, normalizedAppRoot);
 
-    if (!dryRun && removeInstructionGitignoreEntries({ rootDir: normalizedAppRoot, instructionDefinitions: appInstructions }))
+    if (mode === 'monorepo') {
+        const retiredAppRootFiles = removeManagedInstructionFiles(
+            normalizedAppRoot,
+            [...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions],
+            '[agents]',
+            path.join(coreRoot, 'agents', 'project'),
+            {
+                dryRun,
+            },
+        );
+        mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
+    }
+
+    const appGitignoreCleanupInstructions =
+        mode === 'monorepo'
+            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions]
+            : appInstructions;
+
+    if (
+        !dryRun &&
+        removeInstructionGitignoreEntries({
+            rootDir: normalizedAppRoot,
+            instructionDefinitions: appGitignoreCleanupInstructions,
+        })
+    )
         result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
 
     return result;
@@ -253,6 +292,7 @@ function ensureInstructionFiles(
         blocked: [],
         created: [],
         overwritten: [],
+        removed: [],
         skipped: [],
         updated: [],
     };
@@ -268,13 +308,21 @@ function ensureInstructionFiles(
             continue;
         }
 
+        const instructionContent = renderProjectInstructionContent({
+            instructionDefinition,
+            managedSourceRoot,
+            managedSectionContent,
+        });
         const existingState = inspectExistingPath({
             managedSourceRoot,
             projectFilepath,
         });
 
         if (existingState.kind === 'file') {
-            const nextContent = upsertManagedInstructionSection(existingState.content, managedSectionContent);
+            const nextContent =
+                instructionDefinition.content === 'source'
+                    ? instructionContent
+                    : upsertManagedInstructionSection(existingState.content, instructionContent);
             if (nextContent === existingState.content) {
                 result.skipped.push(relativeProjectPath);
                 continue;
@@ -289,7 +337,7 @@ function ensureInstructionFiles(
         if (existingState.kind === 'managed-different') {
             if (!dryRun) {
                 fs.removeSync(projectFilepath);
-                fs.writeFileSync(projectFilepath, managedSectionContent);
+                fs.writeFileSync(projectFilepath, instructionContent);
             }
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
@@ -305,14 +353,14 @@ function ensureInstructionFiles(
         if (existingState.kind === 'blocked') {
             if (!dryRun) {
                 fs.removeSync(projectFilepath);
-                fs.writeFileSync(projectFilepath, managedSectionContent);
+                fs.writeFileSync(projectFilepath, instructionContent);
             }
             result.overwritten.push(relativeProjectPath);
             logVerbose(`${logPrefix} Replaced ${relativeProjectPath}`);
             continue;
         }
 
-        if (!dryRun) fs.writeFileSync(projectFilepath, managedSectionContent);
+        if (!dryRun) fs.writeFileSync(projectFilepath, instructionContent);
         result.created.push(relativeProjectPath);
         logVerbose(`${logPrefix} Created ${relativeProjectPath}`);
     }
@@ -320,6 +368,74 @@ function ensureInstructionFiles(
     return result;
 }
 
+function removeManagedInstructionFiles(
+    rootDir: string,
+    instructionDefinitions: TAgentInstructionDefinition[],
+    logPrefix: string,
+    managedSourceRoot: string,
+    {
+        dryRun,
+    }: {
+        dryRun: boolean;
+    },
+): TEnsureInstructionFilesResult {
+    const result: TEnsureInstructionFilesResult = {
+        blocked: [],
+        created: [],
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+    };
+
+    for (const instructionDefinition of instructionDefinitions) {
+        const projectFilepath = path.join(rootDir, instructionDefinition.projectPath);
+        const projectParentDir = path.dirname(projectFilepath);
+        const relativeProjectPath = path.relative(rootDir, projectFilepath) || '.';
+
+        if (!fs.existsSync(projectParentDir)) continue;
+
+        const existingState = inspectExistingPath({
+            managedSourceRoot,
+            projectFilepath,
+        });
+
+        if (existingState.kind === 'missing') continue;
+
+        if (existingState.kind === 'managed-different') {
+            if (!dryRun) fs.removeSync(projectFilepath);
+            result.removed.push(relativeProjectPath);
+            logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+            continue;
+        }
+
+        if (existingState.kind === 'file') {
+            const retainedContent = removeManagedInstructionContent(existingState.content);
+
+            if (retainedContent === undefined) {
+                result.skipped.push(relativeProjectPath);
+                continue;
+            }
+
+            if (retainedContent.trim() === '') {
+                if (!dryRun) fs.removeSync(projectFilepath);
+                result.removed.push(relativeProjectPath);
+                logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+                continue;
+            }
+
+            if (!dryRun) fs.writeFileSync(projectFilepath, retainedContent);
+            result.updated.push(relativeProjectPath);
+            logVerbose(`${logPrefix} Removed retired managed section from ${relativeProjectPath}`);
+            continue;
+        }
+
+        result.skipped.push(relativeProjectPath);
+    }
+
+    return result;
+}
+
 function inspectExistingPath({
     managedSourceRoot,
     projectFilepath,
@@ -377,57 +493,108 @@ function mergeInstructionResults(
 ) {
     result.created.push(...next.created.map((entry) => formatResultPath(rootDir, entry)));
     result.overwritten.push(...next.overwritten.map((entry) => formatResultPath(rootDir, entry)));
+    result.removed.push(...next.removed.map((entry) => formatResultPath(rootDir, entry)));
     result.updated.push(...next.updated.map((entry) => formatResultPath(rootDir, entry)));
     result.skipped.push(...next.skipped.map((entry) => formatResultPath(rootDir, entry)));
     result.blocked.push(...next.blocked.map((entry) => formatResultPath(rootDir, entry)));
 }
 
-function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs) {
-    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
-    if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
+function renderProjectInstructionContent({
+    instructionDefinition,
+    managedSourceRoot,
+    managedSectionContent,
+}: {
+    instructionDefinition: TAgentInstructionDefinition;
+    managedSourceRoot: string;
+    managedSectionContent: string;
+}) {
+    if (instructionDefinition.content !== 'source') return managedSectionContent;
+
+    return renderSingleProjectInstruction({
+        managedSourceRoot,
+        projectPath: instructionDefinition.projectPath,
+    });
+}
 
-    const sourceFiles = collectMarkdownFiles(agentSourceRoot).sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+function renderSingleProjectInstruction({
+    managedSourceRoot,
+    projectPath,
+}: {
+    managedSourceRoot: string;
+    projectPath: string;
+}) {
+    const sourceFilepath = path.join(managedSourceRoot, projectPath);
+    if (!fs.existsSync(sourceFilepath)) throw new Error(`Missing project instruction source file: ${sourceFilepath}`);
+
+    const content = fs.readFileSync(sourceFilepath, 'utf8');
+    const demotedContent = demoteMarkdownHeadings(content).trim();
     const lines = [
         managedInstructionSectionHeader,
         managedInstructionSectionStart,
         '',
         managedInstructionSectionIntro,
         '',
+        `## Source: ${normalizeProjectPathForGitignore(projectPath)}`,
+        '',
     ];
 
-    for (const sourceFile of sourceFiles) {
-        const content = fs.readFileSync(sourceFile.filepath, 'utf8');
-        const demotedContent = demoteMarkdownHeadings(content).trim();
-
-        lines.push(`## Source: ${sourceFile.relativePath}`, '');
-        if (demotedContent) lines.push(demotedContent, '');
-    }
-
+    if (demotedContent) lines.push(demotedContent, '');
     lines.push(managedInstructionSectionEnd, '');
 
     return lines.join('\n');
 }
 
-function collectMarkdownFiles(rootDir: string, currentDir = rootDir): { filepath: string; relativePath: string }[] {
-    const files: { filepath: string; relativePath: string }[] = [];
-
-    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
-        const filepath = path.join(currentDir, entry.name);
-
-        if (entry.isDirectory()) {
-            files.push(...collectMarkdownFiles(rootDir, filepath));
-            continue;
-        }
+function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs) {
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+    if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const lines = [
+        managedInstructionSectionHeader,
+        managedInstructionSectionStart,
+        '',
+        managedInstructionSectionIntro,
+        '',
+        '## Agent Routing Contract',
+        '',
+        'Proteum CLI commands are optimized for agents. Do not load the whole instruction corpus up front.',
+        '',
+        '1. Start ambiguous, generated, connected, route, controller, file, or error work with `npx proteum orient <query>`.',
+        '2. Read only the files returned in `mustRead` plus the conditional docs that match the current task.',
+        '3. Use `npx proteum runtime status` before starting a dev server, so an existing tracked session can be reused.',
+        '4. Use `npx proteum diagnose <target>` for request-time issues before raw trace, perf, browser, or broad source search.',
+        '5. Use `--full`, `--manifest`, or `--events` only when a compact CLI response says the omitted detail is needed.',
+        '',
+        '## Always-On Safety',
+        '',
+        '- Never edit generated files under `.proteum`.',
+        '- Never create or edit Prisma migration files manually.',
+        '- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX`.',
+        '- If `schema.prisma` changes, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue` before validation.',
+        '- Do not run `git restore` or `git reset`.',
+        '- Keep `proteum dev` sessions tracked with explicit session files and do not replace another live session.',
+        '',
+        '## Routing Table',
+        '',
+        '- Raw errors, failing requests, traces, perf, or reproduction: read `diagnostics.md`.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing.',
+        '- Client files or pages: read `client/AGENTS.md`; for page route/data/render work also read `client/pages/AGENTS.md`.',
+        '- Server services: read `server/services/AGENTS.md`.',
+        '- Manual server routes: read `server/routes/AGENTS.md`.',
+        '- E2E work: read `tests/e2e/AGENTS.md` and `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`.',
+        '- Package, runtime, build, or client-performance decisions: read `optimizations.md` after implementation or when explicitly optimizing.',
+        '',
+        '## Canonical Source Map',
+        '',
+        `- Root contract fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'AGENTS.md'))}`,
+        `- Diagnostics fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'diagnostics.md'))}`,
+        `- Optimization fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'optimizations.md'))}`,
+        `- Coding style fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'CODING_STYLE.md'))}`,
+        '',
+    ];
 
-        files.push({
-            filepath,
-            relativePath: normalizeProjectPathForGitignore(path.relative(rootDir, filepath)),
-        });
-    }
+    lines.push(managedInstructionSectionEnd, '');
 
-    return files;
+    return lines.join('\n');
 }
 
 function demoteMarkdownHeadings(content: string) {
@@ -472,6 +639,16 @@ function upsertManagedInstructionSection(content: string, managedSectionContent:
     return joinMarkdownSections([before, managedSectionContent, after]);
 }
 
+function removeManagedInstructionContent(content: string) {
+    const managedRange = findManagedInstructionSectionRange(content) || findLegacyManagedInstructionStubRange(content);
+    if (!managedRange) return undefined;
+
+    const before = content.slice(0, managedRange.start);
+    const after = content.slice(managedRange.end);
+
+    return joinMarkdownSections([before, after]);
+}
+
 function findManagedInstructionSectionRange(content: string) {
     const markerStartIndex = content.indexOf(managedInstructionSectionStart);
     if (markerStartIndex === -1) return undefined;

package/common/dev/inspection.ts

@@ -713,12 +713,25 @@ const resolveGuidanceFile = ({
     fallbackFilepath: string;
     relativePath: string;
 }) => {
-    const localFilepath = joinPath(appRoot, relativePath);
-    if (fileExists(localFilepath)) return { filepath: localFilepath, warning: undefined as string | undefined };
+    const resolvedAppRoot = resolvePath(appRoot);
+    const repoRoot = findRepoRoot(resolvedAppRoot);
+    let currentRoot = resolvedAppRoot;
+
+    while (true) {
+        const localFilepath = joinPath(currentRoot, relativePath);
+        if (fileExists(localFilepath)) return { filepath: localFilepath, warning: undefined as string | undefined };
+
+        if (currentRoot === repoRoot) break;
+
+        const parentRoot = dirnamePath(currentRoot);
+        if (parentRoot === currentRoot) break;
+
+        currentRoot = parentRoot;
+    }
 
     return {
         filepath: fallbackFilepath,
-        warning: `Missing ${relativePath} in ${appRoot}; using ${fallbackFilepath}.`,
+        warning: `Missing ${relativePath} in ${appRoot} and its repository ancestors; using ${fallbackFilepath}.`,
     };
 };
 
@@ -1143,12 +1156,20 @@ export const explainOwner = (manifest: TProteumManifest, query: string): TExplai
     const normalizedQuery = normalizeText(query);
     if (!normalizedQuery) return { matches: [], normalizedQuery, query };
 
-    const matches = buildManifestEntries(manifest)
-        .map((entry) => {
-            const { score, matchedOn } = scoreOwnerMatch(query, entry);
-            return score > 0 ? toOwnerMatch(entry, score, matchedOn) : undefined;
-        })
-        .filter((match): match is TExplainOwnerMatch => match !== undefined)
+    const entries = buildManifestEntries(manifest);
+    const scoredMatches =
+        normalizedQuery === '/'
+            ? entries
+                  .filter((entry) => (entry.kind === 'route' || entry.kind === 'controller') && normalizeText(entry.label) === '/')
+                  .map((entry) => toOwnerMatch(entry, 200, ['/']))
+            : entries
+                  .map((entry) => {
+                      const { score, matchedOn } = scoreOwnerMatch(query, entry);
+                      return score > 0 ? toOwnerMatch(entry, score, matchedOn) : undefined;
+                  })
+                  .filter((match): match is TExplainOwnerMatch => match !== undefined);
+
+    const matches = scoredMatches
         .sort((left, right) => right.score - left.score || left.kind.localeCompare(right.kind) || left.label.localeCompare(right.label))
         .slice(0, 12);