engineering-memory 0.2.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/dist/src/config.js

@@ -57,5 +57,8 @@ export const endpoints = {
     projectResolve: '/projects/resolve',
     projectBind: (projectId) => `/projects/${projectId}/bind`,
     projectMemberAdd: (projectId) => `/projects/${projectId}/members`,
+    projectLink: '/projects/link',
+    projectUnlink: '/projects/unlink',
+    projectLinks: (projectId) => `/projects/${projectId}/links`,
 };
 //# sourceMappingURL=config.js.map

package/runtime/dist/src/git/git-inspector.js

@@ -262,6 +262,20 @@ export class GitInspector {
             mode: fileStat.mode & 0o111 ? '100755' : '100644',
         };
     }
+    async clone(repositoryUrl, targetPath) {
+        if (!/^https:\/\//.test(repositoryUrl)) {
+            return {
+                cloned: false,
+                reason: 'only an https repository address is cloned',
+            };
+        }
+        const result = await this.runner.run('git', ['clone', repositoryUrl, targetPath], {
+            cwd: process.cwd(),
+        });
+        return result.exitCode === 0
+            ? { cloned: true, reason: '' }
+            : { cloned: false, reason: result.stderr.trim().slice(0, 400) };
+    }
     async pathHistorySubjects(repoRoot, paths) {
         if (paths.length === 0)
             return [];

package/runtime/dist/src/mcp/tool-definitions.js

@@ -73,6 +73,10 @@ export const engineeringMemoryToolNames = [
     'project.list',
     'project.resolve',
     'project.member_add',
+    'project.clone',
+    'project.link',
+    'project.unlink',
+    'project.links',
     'auth.status',
     'auth.signin_browser',
     'auth.logout',
@@ -445,6 +449,31 @@ export function registerEngineeringMemoryTools(server, service) {
             confirmLocalOnly: z.boolean().optional(),
         }),
     }, async (input) => toolResult(await service.authLogout(input)));
+    server.registerTool('project.clone', {
+        description: "Clone a project's repository into an empty directory, for a project this account belongs to that has a repository address recorded. The clone uses the developer's own Git credentials; Engineering Memory never asks for, stores or transmits one, so an access failure is reported and left to them.",
+        inputSchema: z.object({
+            projectId: z.string().min(1),
+            targetPath: z.string().min(1).describe('Where to place the checkout.'),
+        }),
+    }, async (input) => toolResult(await service.projectClone(input)));
+    server.registerTool('project.link', {
+        description: 'Link a backend project to a frontend project of the same organization, so each side sees the endpoint and flow contracts of the other. Only an organization owner may do this.',
+        inputSchema: z.object({
+            backendProjectId: z.string().min(1),
+            frontendProjectId: z.string().min(1),
+        }),
+    }, async (input) => toolResult(await service.projectLink(input)));
+    server.registerTool('project.unlink', {
+        description: 'Remove the link between a backend and a frontend project. Only an organization owner may do this.',
+        inputSchema: z.object({
+            backendProjectId: z.string().min(1),
+            frontendProjectId: z.string().min(1),
+        }),
+    }, async (input) => toolResult(await service.projectUnlink(input)));
+    server.registerTool('project.links', {
+        description: 'List the projects linked to this one, and which side of the product each is.',
+        inputSchema: z.object({ projectId: z.string().min(1) }),
+    }, async (input) => toolResult(await service.projectLinks(input)));
     server.registerTool('auth.status', {
         description: 'Check whether OS credential storage contains an active local Engineering Memory session.',
         inputSchema: z.object({}),

package/runtime/dist/src/runtime/bridge-service.js

@@ -474,6 +474,73 @@ export class BridgeService {
             });
         });
     }
+    async clonableProjects() {
+        try {
+            const response = await this.dependencies.client.request(endpoints.projectList);
+            const projects = Array.isArray(response.data) ? response.data : [];
+            return projects.flatMap((entry) => {
+                const project = objectValue(entry);
+                const repositoryUrl = project?.repositoryUrl;
+                return project && typeof repositoryUrl === 'string' && repositoryUrl
+                    ? [
+                        asJsonValue({
+                            projectId: project.id,
+                            name: project.name,
+                            framework: project.framework ?? null,
+                            repositoryUrl,
+                        }),
+                    ]
+                    : [];
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    async projectClone(input) {
+        return await this.execute(async () => {
+            const projects = await this.clonableProjects();
+            const project = projects
+                .map((entry) => objectValue(entry))
+                .find((entry) => entry?.projectId === input.projectId);
+            if (!project) {
+                throw new Error('That project has no repository address recorded, or this account is not a member of it. An organization owner records the address.');
+            }
+            const result = await this.dependencies.repositories.git.clone(String(project.repositoryUrl), input.targetPath);
+            if (!result.cloned) {
+                throw new Error(`The repository could not be cloned: ${result.reason}. Engineering Memory never handles Git credentials, so this is between the developer's own Git configuration and the host.`);
+            }
+            return asJsonValue({
+                cloned: true,
+                projectId: input.projectId,
+                path: input.targetPath,
+            });
+        });
+    }
+    async projectLink(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectLink, {
+                method: 'POST',
+                body: cleanJson(input),
+            });
+            return asJsonValue({ link: response.data });
+        });
+    }
+    async projectUnlink(input) {
+        return await this.execute(async () => {
+            await this.dependencies.client.request(endpoints.projectUnlink, {
+                method: 'POST',
+                body: cleanJson(input),
+            });
+            return asJsonValue({ unlinked: true });
+        });
+    }
+    async projectLinks(input) {
+        return await this.execute(async () => {
+            const response = await this.dependencies.client.request(endpoints.projectLinks(input.projectId), { method: 'POST', body: {} });
+            return asJsonValue({ links: objectValue(response.data)?.links ?? [] });
+        });
+    }
     async sessionAnswerShadowNotice(input) {
         return await this.execute(async () => {
             await this.dependencies.shadowNotices.answer(input.resourceId, input.revisionNumber);
@@ -1222,11 +1289,16 @@ export class BridgeService {
                 repository = await this.dependencies.repositories.resolve(input.repoRoot ?? process.cwd());
             }
             catch (error) {
+                const authenticated = authentication.authenticated === true;
+                const clonable = authenticated ? await this.clonableProjects() : [];
                 return asJsonValue({
-                    authenticated: authentication.authenticated === true,
+                    authenticated,
                     repository: null,
                     decision: 'none',
-                    nextAction: 'This directory is not a Git repository, so Engineering Memory has nothing to bind. Work normally and say nothing about it.',
+                    clonableProjects: clonable,
+                    nextAction: clonable.length > 0
+                        ? 'This directory is not a Git repository. Offer the listed projects and clone the one the user chooses with project.clone. Do not mention Engineering Memory otherwise.'
+                        : 'This directory is not a Git repository, so Engineering Memory has nothing to bind. Work normally and say nothing about it.',
                     reason: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -1794,6 +1866,7 @@ export class BridgeService {
         return await this.deliverCloseIntent(repository, body, intent.taskChanges, true);
     }
     async deliverCloseIntent(repository, body, taskChanges, recoveredAfterResponseLoss) {
+        const touchedContract = taskChanges.some((change) => /\.controller\.[tj]s$/.test(change.path));
         let response;
         try {
             response = await this.dependencies.client.request(endpoints.taskClose, {
@@ -1828,7 +1901,7 @@ export class BridgeService {
             ...closedTask,
             repository: publicRepository(repository),
             recoveredAfterResponseLoss,
-            delivery: deliveryQuestion(),
+            delivery: deliveryQuestion(touchedContract),
         });
     }
     async seedResumeSnapshot(pointer, backendPatch) {
@@ -2078,7 +2151,7 @@ function entryNextAction(authenticated, decision) {
     }
     return 'Ask which organization and then which project, whatever the user asked for, listing what they already have with the option to create a new one last. Switching Engineering Memory off in this repository is the other answer, and it is remembered.';
 }
-function deliveryQuestion() {
+function deliveryQuestion(touchedContract = false) {
     return asJsonValue({
         required: true,
         question: 'The task is closed and nothing has been committed. Ask the user which of these to do, and do only what they choose.',
@@ -2096,6 +2169,11 @@ function deliveryQuestion() {
                 input: 'base branch the pull request targets',
             },
         ],
+        ...(touchedContract
+            ? {
+                alsoAsk: 'This task changed an endpoint contract. Ask whether to document the change for the linked project, and if so write what the other side must do differently with memory.propose_revision as an integration_note.',
+            }
+            : {}),
         afterPullRequest: 'Do not end the turn once a pull request exists. Check whether it merges cleanly, report the conflicting files if it does not, and ask whether to resolve them before touching anything.',
     });
 }

package/skill/references/lifecycle.md

@@ -25,14 +25,29 @@ This is what makes the difference between changing code and understanding it. A
 A request can be as short as "add the KYC flow from Figma". That is enough, and it is not a licence to guess. Work it out:
 
 1. The Figma address arrives in the core pack as the `figma_reference` record. Never ask where the design lives; read it. If the user names a different file, that is a correction to that record — propose the revision and ask for approval in the same reply, so the next session already knows.
-2. Ask for existing flows with `memory.query` naming the `flow_logic` kind. If the flow is already recorded, read it and its history before touching anything.
-3. Read the flow in Figma: which frames belong to it, the order its prototype links imply, and the node id of every screen. A file-level link is orientation, not evidence.
+2. Ask for existing flows with `memory.query` naming the `flow_logic` kind. If the flow is already recorded, read it and its history before touching anything — including a record belonging to the linked project on the other side of the product, which arrives in the core pack. An approved flow record outranks re-deriving the same flow from the design, and deriving it twice is how two halves of one product end up disagreeing about what the steps are.
+3. Read the flow in Figma, at orientation depth only: which frames belong to it, the order its prototype links imply, and the node id of every screen. A file-level link is orientation, not evidence. Stop there — geometry, fills, typography and tokens belong to the screen being built, read at the moment it is built, not gathered for the whole flow up front. Read this yourself rather than delegating it; nothing else can proceed until it is answered, so a second agent only adds the wait.
 4. Read what surrounds it — the screen records the flow starts from and returns to, the navigation contract, the trackers that already exist — and pull `memory.history` wherever the header shows earlier work or a run of corrections.
 5. Decide the entry point, the order, whether a tracker is needed and exactly what it carries, and where the flow ends.
 6. Ask the user what neither Figma nor memory can answer. Where a flow is entered from and what abandoning it halfway does are almost never in the design. Never invent them, and never invent the content of a document the flow displays.
 
 Then propose the `flow_logic` record and stop. The plan is not a message in the chat; it is the proposal, and the user approving it is the approval. Do not write the second screen before that approval exists — a flow's shape replicated across six screens costs six times as much to undo, and verification refuses a task that adds several screens without an approved flow record reconciled to it.
 
+### Work that spans both sides of a product
+
+When the request covers both halves of a linked product — a flow that needs endpoints as well
+as screens — and the user's discipline covers both, it is one work item and two tasks: one in
+each repository. Verification and the commit gate stay per repository because a commit is.
+
+Ask which side to start on, propose the work item key, and open the task in the repository
+being worked in. When the work moves to the other side, open its task with the same
+`workItemKey` and that repository's root — every tool takes `repoRoot`, and both stay open at
+once. `context.prepare_change` then returns `siblingTasks`: the other task's objective, status
+and recent checkpoints, so a decision taken on one side is visible on the other without anyone
+repeating it.
+
+Do not open the second task speculatively. Open it when the work actually reaches that side.
+
 ### A task that reports a defect
 
 Settle first whether the report is about what the user sees or where they go. If it is, the

package/skill/references/memory-updates.md

@@ -22,4 +22,12 @@ Screen logic is canonical in the backend. A screen revision should cover purpose
 
 Component mappings should cover the Flutter symbol and path, public API, purpose, states, design tokens, responsive behavior, Figma file and exact node IDs, assets, usage guidance, tests, selectors, and evidence. Mark missing or partial Figma evidence instead of inventing node IDs.
 
+A backend project records three kinds instead of screens and components, and which kinds a project has is declared in its project profile rather than assumed.
+
+A `module_logic` record covers one resource: what it is for, the entities it owns, the endpoints it exposes, the guards that protect them, the background jobs and queues it runs, what it depends on and why that dependency exists.
+
+A `data_model` record covers one entity: its columns and their types, its relations, what it inherits from the base entity, and every index it declares **with the query that index exists to serve**. An index nobody can name a query for is reported as a finding rather than recorded as a fact.
+
+An `api_endpoint` record covers one route and is the surface a client binds to: method and path, the request DTO, the response DTO, the guards, the error codes it can return, the localization keys it uses, its pagination shape, and which client consumes it. When a linked project exists, these are the records that cross to it, so they are written for a reader on the other side of the wire rather than for the person who wrote the controller.
+
 Do not send full source trees, generated files, vendor assets, raw diffs, credentials, or user data as memory content. Prefer relative paths, symbols, hashes, contract summaries, exact approved Figma identifiers, and bounded task-specific evidence.

package/skill/references/questionnaires.md

@@ -113,6 +113,26 @@ Offer the product option whenever the classification supports it, and say plainl
 
 For any permanent option, show the old rule, proposed rule, reason, affected areas, and regression evidence. Create a proposal but do not approve it until the user explicitly confirms the proposal review.
 
+## Work Across Both Sides
+
+When a request covers a linked backend and frontend and the user's discipline covers both, say
+so and ask which side to start on and what to call the work item — offering the task
+identifier if there is one. Confirm before opening the task on the second side; it is opened
+when the work reaches it, not in advance.
+
+When the discipline covers only one side, say plainly which part of the request this account
+can carry and leave the rest for whoever holds the other discipline.
+
+## Documenting for the Linked Project
+
+When a task changed anything an `api_endpoint` record covers, the delivery question gains an
+option to document the change for the linked project. Take it when the other side has to do
+something differently: a changed request or response shape, a new error code, a route that
+moved. Say what changed and what the other side must do, not what was refactored internally.
+
+A note can also be asked for at any time, in a chat of its own, for work that was already
+finished.
+
 ## Delivery
 
 After `task.close`, and every time, ask the user what to do with the finished work. Nothing has been committed at this point and nothing may be until they answer. Offer exactly these:

package/skill/references/scaffolding.md

@@ -1,6 +1,6 @@
 # Greenfield Scaffolding
 
-Architecture templates are organization-scoped source modules stored as approved engineering memory. A greenfield project reproduces the team architecture from those modules instead of re-deriving it from prose rules. The backend stores, versions and authorizes them; it never generates code. The agent applies the rename map and writes every file itself.
+Architecture templates are source modules stored as approved engineering memory. The product ships a starter for each stack it supports and an organization may hold its own, which takes precedence; a template never belongs to a single project. A greenfield project reproduces the team architecture from those modules instead of re-deriving it from prose rules. The backend stores, versions and authorizes them; it never generates code. The agent applies the rename map and writes every file itself.
 
 ## Organization first
 
@@ -15,7 +15,7 @@ Call `organization.list` and ask the user which organization the project belongs
 3. Present the optional modules through the native questionnaire. A package-shaped project usually skips the application modules; an application usually takes them.
 4. Confirm the naming decisions in one questionnaire: package name and the concrete class name behind every rename placeholder. Never invent a name the user did not choose.
 5. For each module in `applyOrder`, call `architecture.module`, apply the rename map and string replacements, write the files, then call `architecture.record_application` with the template path and the written path of every file. Respect `dependsOn`; do not reorder modules.
-6. Merge every module's `pubspecDependencies` into the manifest file. Keep the existing constraint when a dependency already exists and report the conflict.
+6. Merge every module's `packageDependencies` into the project's dependency manifest — `pubspec.yaml`, `package.json`, whatever the stack uses. Keep the existing constraint when a dependency already exists and report the conflict.
 7. Satisfy the `assetContract`. Ask the user for each required asset role. Never invent an asset, never ship a placeholder binary, and never copy a licensed font from another project.
 8. Resolve every `tenantSpecific` point through the questionnaire: base URLs, backend header contracts, storage key prefixes, supported locales, bundle identifiers. These are deliberately absent from the template. Do not guess them.
 9. Run code generation and localization generation, then static analysis and tests. Record the validation checkpoints as usual.
@@ -27,7 +27,7 @@ Verification exempts a scaffolded file only while its working-tree hash still eq
 
 Nothing else is relaxed. A file you edit after scaffolding no longer matches its recorded hash and falls back to the normal screen and component memory rules. A file the template never declared is never exempt. A scaffold task that recorded no applied module fails verification, so scaffold mode cannot be used to skip memory obligations on ordinary work.
 
-Write the first real screen as a separate `write` task. Do not extend the scaffold task to cover feature work.
+Write the first real unit of work — a screen, a resource — as a separate `write` task. Do not extend the scaffold task to cover feature work.
 
 ## Keeping templates current