proteum 2.5.6 → 2.5.7

package/agents/project/AGENTS.md

@@ -81,7 +81,6 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
 - Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
-- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 

package/agents/project/root/AGENTS.md

@@ -67,7 +67,6 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
 - For production changes, always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every ordinary change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; downstream app commit-only workflows run `proteum refresh`, then targeted lint, typecheck, and test commands in parallel unless the user explicitly requests more, while framework-repo commits skip this downstream app verification. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
 - Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
-- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 

package/cli/utils/agents.ts

@@ -16,6 +16,7 @@ type TProjectInstructionArgs = {
     appRoot?: string;
     coreRoot: string;
     includeMonorepoRegistry?: boolean;
+    instructionRoot: string;
     monorepoRegistryCurrentAppRoot?: string;
     monorepoRoot?: string;
 };
@@ -106,6 +107,14 @@ const sharedTestAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: path.join('tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), ensureParentDir: true, content: 'source' },
 ];
 
+const projectInstructionSourceMapEntries = [
+    { label: 'Root contract fallback', projectPath: 'AGENTS.md' },
+    { label: 'Documentation fallback', projectPath: 'DOCUMENTATION.md' },
+    { label: 'Diagnostics fallback', projectPath: 'diagnostics.md' },
+    { label: 'Optimization fallback', projectPath: 'optimizations.md' },
+    { label: 'Coding style fallback', projectPath: 'CODING_STYLE.md' },
+];
+
 const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
@@ -164,6 +173,7 @@ export function configureProjectAgentInstructions({
     const appEmbeddedInstructions = renderEmbeddedProjectInstructions({
         appRoot: normalizedAppRoot,
         coreRoot,
+        instructionRoot: normalizedAppRoot,
         monorepoRoot: normalizedMonorepoRoot,
     });
     const rootEmbeddedInstructions =
@@ -172,6 +182,7 @@ export function configureProjectAgentInstructions({
                   appRoot: normalizedAppRoot,
                   coreRoot,
                   includeMonorepoRegistry: true,
+                  instructionRoot: normalizedMonorepoRoot,
                   monorepoRegistryCurrentAppRoot: markCurrentAppInMonorepoRegistry ? normalizedAppRoot : undefined,
                   monorepoRoot: normalizedMonorepoRoot,
               })
@@ -973,6 +984,7 @@ function renderEmbeddedProjectInstructions({
     appRoot,
     coreRoot,
     includeMonorepoRegistry = false,
+    instructionRoot,
     monorepoRegistryCurrentAppRoot,
     monorepoRoot,
 }: TProjectInstructionArgs) {
@@ -1063,11 +1075,14 @@ function renderEmbeddedProjectInstructions({
         '',
         '## Canonical Source Map',
         '',
-        `- Root contract fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'AGENTS.md'))}`,
-        `- Documentation fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'DOCUMENTATION.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'))}`,
+        ...projectInstructionSourceMapEntries.map(
+            ({ label, projectPath }) =>
+                `- ${label}: ${formatProjectInstructionSourceMapPath({
+                    coreRoot,
+                    instructionRoot,
+                    projectPath,
+                })}`,
+        ),
         '',
     ];
 
@@ -1209,6 +1224,41 @@ function formatResultPath(rootDir: string, relativePath: string) {
     return normalizeProjectPathForGitignore(path.join(rootDir, relativePath));
 }
 
+function formatProjectInstructionSourceMapPath({
+    coreRoot,
+    instructionRoot,
+    projectPath,
+}: {
+    coreRoot: string;
+    instructionRoot: string;
+    projectPath: string;
+}) {
+    const sourceRoot = resolveProjectInstructionSourceMapRoot({ coreRoot, instructionRoot });
+    const sourcePath = path.resolve(sourceRoot, 'agents', 'project', projectPath);
+    const relativePath = path.relative(path.resolve(instructionRoot), sourcePath);
+
+    return normalizeProjectPathForGitignore(relativePath);
+}
+
+function resolveProjectInstructionSourceMapRoot({ coreRoot, instructionRoot }: { coreRoot: string; instructionRoot: string }) {
+    const visibleInstallRoot = findVisibleProteumInstructionRoot(instructionRoot);
+
+    return visibleInstallRoot || coreRoot;
+}
+
+function findVisibleProteumInstructionRoot(startRoot: string) {
+    let currentPath = path.resolve(startRoot);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules', 'proteum');
+        if (fs.existsSync(path.join(candidate, 'agents', 'project'))) return candidate;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+}
+
 export function resolveCanonicalPath(inputPath: string) {
     const resolvedPath = path.resolve(inputPath);
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.6",
+	"version": "2.5.7",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/agents-utils.test.cjs

@@ -38,8 +38,9 @@ const pathEntryExists = (filepath) => {
 
 const makeTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-agents-'));
 
-const createCoreFixture = () => {
-    const root = makeTempRoot();
+const normalizePath = (value) => value.replace(/\\/g, '/');
+
+const createCoreFixture = (root = makeTempRoot()) => {
     const agentsRoot = path.join(root, 'agents', 'project');
 
     writeFile(path.join(agentsRoot, 'AGENTS.md'), '# Root Contract\n\n- Root rule\n');
@@ -61,6 +62,20 @@ const createCoreFixture = () => {
     return root;
 };
 
+const expectedSourceMapPath = ({ coreRoot, instructionRoot, projectPath }) =>
+    normalizePath(path.relative(instructionRoot, path.join(coreRoot, 'agents', 'project', projectPath)));
+
+const assertSourceMapPath = ({ content, coreRoot, instructionRoot, label, projectPath }) => {
+    assert.equal(
+        content.includes(`- ${label}: ${expectedSourceMapPath({ coreRoot, instructionRoot, projectPath })}`),
+        true,
+    );
+};
+
+const assertNoAbsoluteCoreSourceMapPath = ({ content, coreRoot }) => {
+    assert.equal(content.includes(normalizePath(path.join(coreRoot, 'agents', 'project'))), false);
+};
+
 const createAppFixture = () => {
     const appRoot = makeTempRoot();
 
@@ -173,6 +188,53 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.doesNotMatch(gitignoreContent, /^\/DOCUMENTATION\.md$/m);
 });
 
+test('standalone configure writes install-relative source map fallbacks', () => {
+    const appRoot = createAppFixture();
+    const coreRoot = createCoreFixture(path.join(appRoot, 'node_modules', 'proteum'));
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+    const agentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+
+    assert.equal(result.blocked.length, 0);
+    assertSourceMapPath({
+        content: agentsContent,
+        coreRoot,
+        instructionRoot: appRoot,
+        label: 'Root contract fallback',
+        projectPath: 'AGENTS.md',
+    });
+    assertSourceMapPath({
+        content: agentsContent,
+        coreRoot,
+        instructionRoot: appRoot,
+        label: 'Documentation fallback',
+        projectPath: 'DOCUMENTATION.md',
+    });
+    assertNoAbsoluteCoreSourceMapPath({ content: agentsContent, coreRoot });
+    assert.match(agentsContent, /Root contract fallback: node_modules\/proteum\/agents\/project\/AGENTS\.md/);
+});
+
+test('standalone configure source map prefers project install over active external core', () => {
+    const activeCoreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    createCoreFixture(path.join(appRoot, 'node_modules', 'proteum'));
+
+    configureProjectAgentInstructions({ appRoot, coreRoot: activeCoreRoot });
+
+    const agentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(agentsContent, /Root contract fallback: node_modules\/proteum\/agents\/project\/AGENTS\.md/);
+    assert.equal(
+        agentsContent.includes(
+            `Root contract fallback: ${expectedSourceMapPath({
+                coreRoot: activeCoreRoot,
+                instructionRoot: appRoot,
+                projectPath: 'AGENTS.md',
+            })}`,
+        ),
+        false,
+    );
+    assertNoAbsoluteCoreSourceMapPath({ content: agentsContent, coreRoot: activeCoreRoot });
+});
+
 test('configure preserves project content outside the managed section', () => {
     const coreRoot = createCoreFixture();
     const appRoot = createAppFixture();
@@ -296,6 +358,22 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(appAgentsContent, /## Agent Routing Contract/);
     assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
     assert.doesNotMatch(appAgentsContent, /Eligible Proteum commands run across the apps below/);
+    assertSourceMapPath({
+        content: fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'),
+        coreRoot,
+        instructionRoot: monorepoRoot,
+        label: 'Root contract fallback',
+        projectPath: 'AGENTS.md',
+    });
+    assertSourceMapPath({
+        content: appAgentsContent,
+        coreRoot,
+        instructionRoot: appRoot,
+        label: 'Root contract fallback',
+        projectPath: 'AGENTS.md',
+    });
+    assertNoAbsoluteCoreSourceMapPath({ content: fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), coreRoot });
+    assertNoAbsoluteCoreSourceMapPath({ content: appAgentsContent, coreRoot });
     assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
     assertClaudeSymlink(appRoot);
     assertClaudeSymlink(appRoot, 'client');
@@ -306,6 +384,28 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.equal(result.removed.some((entry) => entry.endsWith('/apps/product/CODING_STYLE.md')), true);
 });
 
+test('monorepo configure source map uses workspace install from root and nested apps', () => {
+    const activeCoreRoot = createCoreFixture();
+    const monorepoRoot = makeTempRoot();
+    const appRoot = path.join(monorepoRoot, 'apps', 'product');
+
+    createCoreFixture(path.join(monorepoRoot, 'node_modules', 'proteum'));
+    fs.mkdirSync(path.join(monorepoRoot, '.git'));
+    fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"product"}\n');
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+
+    configureProjectAgentInstructions({ appRoot, coreRoot: activeCoreRoot, monorepoRoot });
+
+    const rootAgentsContent = fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8');
+    const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(rootAgentsContent, /Root contract fallback: node_modules\/proteum\/agents\/project\/AGENTS\.md/);
+    assert.match(appAgentsContent, /Root contract fallback: \.\.\/\.\.\/node_modules\/proteum\/agents\/project\/AGENTS\.md/);
+    assertNoAbsoluteCoreSourceMapPath({ content: rootAgentsContent, coreRoot: activeCoreRoot });
+    assertNoAbsoluteCoreSourceMapPath({ content: appAgentsContent, coreRoot: activeCoreRoot });
+});
+
 test('monorepo-wide configure writes shared root once and all app instruction files', () => {
     const coreRoot = createCoreFixture();
     const monorepoRoot = makeTempRoot();