engineering-memory 0.3.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-memory",
-  "version": "0.3.0",
+  "version": "1.0.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',
@@ -376,8 +380,22 @@ export function registerEngineeringMemoryTools(server, service) {
             initialProjectProfile: z.object({
                 title: z.string().min(2),
                 content: z.string().min(2),
-                screenPathPatterns: z.array(z.string().min(1)).min(1),
-                componentPathPatterns: z.array(z.string().min(1)).min(1),
+                discoveryUnits: z
+                    .array(z.object({
+                    kind: z.enum([
+                        'screen_logic',
+                        'component_mapping',
+                        'module_logic',
+                        'data_model',
+                        'api_endpoint',
+                    ]),
+                    patterns: z.array(z.string().min(1)).min(1),
+                }))
+                    .min(1)
+                    .optional()
+                    .describe('What this project calls its units and where they live. A Flutter project declares screen_logic and component_mapping; a backend declares module_logic, data_model and api_endpoint.'),
+                screenPathPatterns: z.array(z.string().min(1)).min(1).optional(),
+                componentPathPatterns: z.array(z.string().min(1)).min(1).optional(),
                 metadata: jsonObject,
                 provenance: jsonObject,
             }),
@@ -445,6 +463,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);
@@ -1062,8 +1129,7 @@ export class BridgeService {
                 !policy ||
                 !marker ||
                 marker.projectId !== project.id ||
-                stringArray(policy.screenPathPatterns).length === 0 ||
-                stringArray(policy.componentPathPatterns).length === 0) {
+                readDiscoveryUnits(policy).length === 0) {
                 throw new Error('Project setup response is not policy-ready');
             }
             const markerPath = await this.dependencies.repositories.writeMarker(repository.repoRoot, project.id);
@@ -1222,11 +1288,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 +1865,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 +1900,7 @@ export class BridgeService {
             ...closedTask,
             repository: publicRepository(repository),
             recoveredAfterResponseLoss,
-            delivery: deliveryQuestion(),
+            delivery: deliveryQuestion(touchedContract),
         });
     }
     async seedResumeSnapshot(pointer, backendPatch) {
@@ -2078,7 +2150,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 +2168,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.',
     });
 }
@@ -2291,18 +2368,11 @@ export function newMemoryResourceCandidate(entry, policy) {
         return [];
     }
     if (policy) {
-        const screen = policy.screenPathPatterns.some((pattern) => globMatches(entry.path, pattern));
-        const component = policy.componentPathPatterns.some((pattern) => globMatches(entry.path, pattern));
-        if (screen && component) {
+        const matched = policy.units.filter((unit) => unit.patterns.some((pattern) => globMatches(entry.path, pattern)));
+        if (matched.length > 1) {
             throw new Error(`Resource discovery policy is ambiguous for path: ${entry.path}`);
         }
-        if (screen) {
-            return [{ path: entry.path, kind: 'screen_logic' }];
-        }
-        if (component) {
-            return [{ path: entry.path, kind: 'component_mapping' }];
-        }
-        return [];
+        return matched[0] ? [{ path: entry.path, kind: matched[0].kind }] : [];
     }
     const extension = entry.path.toLowerCase().match(/\.[^.\/]+$/)?.[0];
     if (!extension ||
@@ -2342,12 +2412,32 @@ function readResourceDiscoveryPolicy(snapshot, activeLease) {
     if (!discovery) {
         return null;
     }
-    const screenPathPatterns = stringArray(discovery.screenPathPatterns);
-    const componentPathPatterns = stringArray(discovery.componentPathPatterns);
-    if (screenPathPatterns.length === 0 || componentPathPatterns.length === 0) {
+    const units = readDiscoveryUnits(discovery);
+    if (units.length === 0) {
         throw new Error('Pinned resource discovery policy is incomplete');
     }
-    return { screenPathPatterns, componentPathPatterns };
+    return { units };
+}
+function readDiscoveryUnits(discovery) {
+    if (!discovery)
+        return [];
+    const declared = Array.isArray(discovery.units) ? discovery.units : null;
+    if (declared) {
+        return declared.flatMap((entry) => {
+            const unit = objectValue(entry);
+            const patterns = stringArray(unit?.patterns);
+            return typeof unit?.kind === 'string' && patterns.length > 0
+                ? [{ kind: unit.kind, patterns }]
+                : [];
+        });
+    }
+    return [
+        { kind: 'screen_logic', patterns: stringArray(discovery.screenPathPatterns) },
+        {
+            kind: 'component_mapping',
+            patterns: stringArray(discovery.componentPathPatterns),
+        },
+    ].filter((unit) => unit.patterns.length > 0);
 }
 function stringArray(value) {
     if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {

package/skill/references/lifecycle.md

@@ -25,7 +25,7 @@ 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.
+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.
@@ -33,6 +33,21 @@ A request can be as short as "add the KYC flow from Figma". That is enough, and
 
 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
@@ -43,6 +58,8 @@ target inferred only from surrounding code. Carry both node ids into the discove
 checkpoint as evidence. A defect in a calculation, a response shape or a service has no
 answer in the design; do not spend the read there.
 
+Name the areas this task works in, against the coverage map the core pack carries. Where an area it touches is marked as having no rule, that is not a reason to stop — it is a finding to raise at self review, so the absence is reported by the product rather than found later by whoever inherits the code.
+
 Do not pull history for everything. Pull it for the records the task actually touches, and for anything the header shows a surprising number of corrections on. Record `task.checkpoint` with type `discovery` and update STATE, DECISIONS, DISCOVERY, and HANDOFF projections through the bridge.
 
 Send calls that do not feed each other in one batch rather than one at a time: reads of any kind, and proposals for different records. Reconcile every record the task touched in a single `task.reconcile` call with `entries`, not one call per record.
@@ -91,7 +108,9 @@ Before validation, read the changed code back against the rules that govern it.
 
 Record `task.self_review` naming the resources reviewed and, for every conflict found, the file, the rule, what was wrong and what was done about it. A review that found nothing records an empty finding list, which is a claim about the work rather than a formality.
 
-`task.verify` refuses without a self review of the current diff. Editing after the review invalidates it, which is the point: the last thing that happens to the code is that someone read it against the rules. This exists because a task once shipped code that broke rules it had been given — the rules were present and correct, and nothing in the lifecycle ever asked whether the result matched them.
+An area the task worked in that the coverage map marks as having no rule is recorded as a finding too, naming the area and what was decided in its absence. That is how the product learns which rule to write next: an area nothing has needed yet can wait, and one a real task just had to improvise in cannot.
+
+This applies to a write task. A read-only task changed nothing, so there is nothing to read back against the rules and `task.self_review` is refused for it; go straight to verification. `task.verify` refuses a write task without a self review of the current diff. Editing after the review invalidates it, which is the point: the last thing that happens to the code is that someone read it against the rules. This exists because a task once shipped code that broke rules it had been given — the rules were present and correct, and nothing in the lifecycle ever asked whether the result matched them.
 
 The review is the agent's own job at the end of the work. Do not wait to be asked for it, and do not treat a passing test suite as a substitute: tests leave a receipt and readability does not, which is exactly why the unreviewed one is the one that degrades.
 

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