amalgm 0.1.107 → 0.1.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.107",
+  "version": "0.1.108",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,
@@ -29,13 +29,13 @@
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openai/codex": "^0.128.0",
-    "@opencode-ai/sdk": "^1.17.5",
+    "@opencode-ai/sdk": "^1.17.6",
     "agent-browser": "^0.27.3",
     "ai": "^6.0.116",
     "better-sqlite3": "^12.10.0",
     "cron-parser": "^5.5.0",
     "ffmpeg-static": "^5.3.0",
-    "opencode-ai": "^1.17.5",
+    "opencode-ai": "^1.17.6",
     "tsx": "^4.21.0",
     "ws": "^8.18.3",
     "zod": "^4.1.8"

package/runtime/scripts/amalgm-mcp/project-context/paths.js

@@ -3,11 +3,14 @@
 /**
  * Project context paths + pure text helpers.
  *
- * Every registered workspace carries `<project>/.amalgm/context/` with three
+ * Every registered workspace carries `<project>/.amalgm/context/` with four
  * markdown docs:
- *   instructions.md   user-authored durable instructions
- *   change-log.md     append-only operational history, newest entry on top
- *   project-state.md  consolidated "where the project stands" snapshot
+ *   project-instructions.md   user-authored durable project instructions
+ *   project-goals.md          durable goals and success criteria
+ *   project-state.md          consolidated "where the project stands" snapshot
+ *   change-log.md             append-only operational history, newest entry on top
+ *
+ * The machine-wide context is `<AMALGM_DIR>/context/system-instructions.md`.
  *
  * This module is dependency-free (no db/event imports) so chat-core and tests
  * can use the path/text helpers without pulling in the store.
@@ -16,13 +19,18 @@
 const path = require('path');
 
 const CONTEXT_DIR_SEGMENTS = ['.amalgm', 'context'];
-const INSTRUCTIONS_FILENAME = 'instructions.md';
+const LEGACY_INSTRUCTIONS_FILENAME = 'instructions.md';
+const SYSTEM_INSTRUCTIONS_FILENAME = 'system-instructions.md';
+const PROJECT_INSTRUCTIONS_FILENAME = 'project-instructions.md';
+const PROJECT_GOALS_FILENAME = 'project-goals.md';
 const CHANGE_LOG_FILENAME = 'change-log.md';
 const PROJECT_STATE_FILENAME = 'project-state.md';
 
 const CHANGE_LOG_TITLE = '# Change Log';
 const PROJECT_STATE_TITLE = '# Project State';
-const INSTRUCTIONS_TITLE = '# Instructions';
+const PROJECT_GOALS_TITLE = '# Project Goals';
+const PROJECT_INSTRUCTIONS_TITLE = '# Project Instructions';
+const SYSTEM_INSTRUCTIONS_TITLE = '# System Instructions';
 
 // "Roughly the last 2,000 words" of history, kept deterministic in chars.
 const CHANGE_LOG_CONTEXT_MAX_CHARS = 12_000;
@@ -36,18 +44,34 @@ function contextRoot(projectPath) {
   return path.join(path.resolve(projectPath), ...CONTEXT_DIR_SEGMENTS);
 }
 
+function systemContextRoot(amalgmDir) {
+  return path.join(path.resolve(amalgmDir), 'context');
+}
+
+function systemContextPaths(amalgmDir) {
+  const root = systemContextRoot(amalgmDir);
+  return {
+    root,
+    instructions: path.join(root, SYSTEM_INSTRUCTIONS_FILENAME),
+  };
+}
+
 function contextPaths(projectPath) {
   const root = contextRoot(projectPath);
   return {
     root,
-    instructions: path.join(root, INSTRUCTIONS_FILENAME),
+    instructions: path.join(root, PROJECT_INSTRUCTIONS_FILENAME),
+    goals: path.join(root, PROJECT_GOALS_FILENAME),
     changeLog: path.join(root, CHANGE_LOG_FILENAME),
     projectState: path.join(root, PROJECT_STATE_FILENAME),
   };
 }
 
 const CONTEXT_DOC_FILENAMES = new Set([
-  INSTRUCTIONS_FILENAME,
+  LEGACY_INSTRUCTIONS_FILENAME,
+  SYSTEM_INSTRUCTIONS_FILENAME,
+  PROJECT_INSTRUCTIONS_FILENAME,
+  PROJECT_GOALS_FILENAME,
   CHANGE_LOG_FILENAME,
   PROJECT_STATE_FILENAME,
 ]);
@@ -246,10 +270,15 @@ module.exports = {
   CHANGE_LOG_FILENAME,
   CHANGE_LOG_TITLE,
   CONTEXT_FILE_MAX_CHARS,
-  INSTRUCTIONS_FILENAME,
-  INSTRUCTIONS_TITLE,
+  LEGACY_INSTRUCTIONS_FILENAME,
+  PROJECT_GOALS_FILENAME,
+  PROJECT_GOALS_TITLE,
+  PROJECT_INSTRUCTIONS_FILENAME,
+  PROJECT_INSTRUCTIONS_TITLE,
   PROJECT_STATE_FILENAME,
   PROJECT_STATE_TITLE,
+  SYSTEM_INSTRUCTIONS_FILENAME,
+  SYSTEM_INSTRUCTIONS_TITLE,
   cappedDocContent,
   changeLogEntriesSince,
   changeLogEntryHeading,
@@ -263,4 +292,6 @@ module.exports = {
   localTimestamp,
   projectPathForContextPath,
   sanitizeChangeLogBody,
+  systemContextPaths,
+  systemContextRoot,
 };

package/runtime/scripts/amalgm-mcp/project-context/prompt.js

@@ -9,7 +9,7 @@
  * contextRevision each session last saw (local_meta), and when the canonical
  * row moved, the next turn gets a compact <project_context_update> prepended.
  * Because the change log is append-only, the delta is cheap: entries newer
- * than the last-seen entry timestamp, plus full project-state/instructions
+ * than the last-seen entry timestamp, plus full project goals/state/instructions
  * only when their revisions changed.
  *
  * Invariant: the prompt for turn N reflects every context write committed
@@ -71,6 +71,7 @@ function writeSeen(sessionId, record) {
         projectId: record.projectId,
         contextRevision: record.contextRevision,
         instructionsRevision: record.files?.instructions?.revision || null,
+        projectGoalsRevision: record.files?.goals?.revision || null,
         projectStateRevision: record.files?.projectState?.revision || null,
         changeLogRevision: record.files?.changeLog?.revision || null,
         latestEntryAtMs: record.files?.changeLog?.latestEntryAtMs ?? null,
@@ -96,8 +97,9 @@ function memoryProtocolBlock() {
     'Project memory is maintained through the memories tool — never by editing these files directly.',
     '- When you complete durable, user-visible work in this project, or make decisions future agents need, call toolbox__memories_append_change_log with a concise markdown body: 3-6 factual bullets such as "- Completed: ...", "- Decisions: ...", "- Notes: ...". No transcripts, no essays; mark uncertain items as open questions.',
     '- The runtime owns timestamps and entry placement. Never write timestamps, never rewrite change-log.md — it is append-only.',
+    '- Call toolbox__memories_write_project_goals when durable goals, success criteria, or intended outcomes have intentionally changed. Goals are desired future state, not progress notes.',
     '- Call toolbox__memories_write_project_state only when the consolidated "where this project stands" snapshot must be rewritten (e.g. after a milestone or when consolidating the change log).',
-    '- instructions.md is user-authored. Do not modify it unless the user explicitly asks.',
+    '- project-instructions.md is user-authored. Do not modify it unless the user explicitly asks.',
     '</project_memory_protocol>',
   ].join('\n');
 }
@@ -111,6 +113,13 @@ function contentBlocks(record) {
       '</project_instructions>',
     ].join('\n'));
   }
+  if (record.prompt?.goals) {
+    blocks.push([
+      `<project_goals path="${escapeAttribute(record.paths?.goals)}">`,
+      record.prompt.goals,
+      '</project_goals>',
+    ].join('\n'));
+  }
   if (record.prompt?.projectState) {
     blocks.push([
       `<project_state path="${escapeAttribute(record.paths?.projectState)}">`,
@@ -140,7 +149,7 @@ function projectContextPromptBlock(contract) {
   const lines = [
     '<project_context>',
     `Project: ${record.name} (${record.projectPath})`,
-    'This is the project\'s durable memory. The change log is operational history (newest first); project state is the consolidated snapshot of where things stand; instructions are user-authored guidance for this project.',
+    'This is the project\'s durable memory. Project instructions are user-authored guidance; project goals are intended outcomes; project state is the current consolidated snapshot; the change log is operational history (newest first).',
     '',
     ...contentBlocks(record).flatMap((block) => [block, '']),
     memoryProtocolBlock(),
@@ -187,6 +196,13 @@ function projectContextTurnUpdateBlock(contract) {
         '</project_instructions>',
       ].join('\n'));
     }
+    if (seen.projectGoalsRevision !== record.files?.goals?.revision && record.prompt?.goals) {
+      blocks.push([
+        `<project_goals path="${escapeAttribute(record.paths?.goals)}">`,
+        record.prompt.goals,
+        '</project_goals>',
+      ].join('\n'));
+    }
     if (seen.projectStateRevision !== record.files?.projectState?.revision && record.prompt?.projectState) {
       blocks.push([
         `<project_state path="${escapeAttribute(record.paths?.projectState)}">`,
@@ -219,7 +235,7 @@ function projectContextTurnUpdateBlock(contract) {
 
   return [
     '<project_context_update>',
-    `Project context for ${record.name} (${record.projectPath}) changed since the last turn. Current state:`,
+    `Project context for ${record.name} (${record.projectPath}) changed since the last turn. Current memory:`,
     '',
     ...blocks.flatMap((block) => [block, '']),
     '</project_context_update>',

package/runtime/scripts/amalgm-mcp/project-context/rest.js

@@ -87,6 +87,7 @@ function writeDocHandler(writeFn) {
 }
 
 const handleWriteProjectState = writeDocHandler(store.writeProjectState);
+const handleWriteProjectGoals = writeDocHandler(store.writeProjectGoals);
 const handleWriteInstructions = writeDocHandler(store.writeInstructions);
 const handleWriteChangeLog = writeDocHandler(store.writeChangeLog);
 
@@ -96,5 +97,6 @@ module.exports = {
   handleList,
   handleWriteChangeLog,
   handleWriteInstructions,
+  handleWriteProjectGoals,
   handleWriteProjectState,
 };

package/runtime/scripts/amalgm-mcp/project-context/store.js

@@ -7,10 +7,12 @@
  * store so timestamps, revisions, the SQLite `project_context` row, and Local
  * Live events stay coherent:
  *
- *   change-log.md     append-only via appendChangeLog (runtime owns the
- *                     timestamp; entries land directly under the title)
- *   project-state.md  latest write wins; revision kept as metadata only
- *   instructions.md   user-authored; latest write wins via the UI path
+ *   change-log.md             append-only via appendChangeLog (runtime owns the
+ *                             timestamp; entries land directly under the title)
+ *   project-goals.md          latest write wins; writable by UI and memories tool
+ *   project-state.md          latest write wins; revision kept as metadata only
+ *   project-instructions.md   user-authored; latest write wins via the UI path
+ *   system-instructions.md    global user-authored instructions under AMALGM_DIR
  *
  * Direct disk edits (editors, agents with their own file tools) are picked up
  * by the per-project fs watcher and the fs REST hooks, which funnel into the
@@ -32,8 +34,11 @@ const { AMALGM_DIR } = require('../config');
 const { canonicalProjectPath } = require('../../lib/project-paths');
 const {
   CHANGE_LOG_TITLE,
-  INSTRUCTIONS_TITLE,
+  LEGACY_INSTRUCTIONS_FILENAME,
+  PROJECT_GOALS_TITLE,
+  PROJECT_INSTRUCTIONS_TITLE,
   PROJECT_STATE_TITLE,
+  SYSTEM_INSTRUCTIONS_TITLE,
   changeLogEntryHeading,
   changeLogRecentWindow,
   cappedDocContent,
@@ -44,6 +49,7 @@ const {
   localTimestamp,
   projectPathForContextPath,
   sanitizeChangeLogBody,
+  systemContextPaths: systemContextPathsForAmalgmDir,
 } = require('./paths');
 
 const RESOURCE = 'project_context';
@@ -59,10 +65,7 @@ function systemProject() {
 }
 
 function systemContextPaths() {
-  // AMALGM_DIR *is* the .amalgm dir, so the system context sits directly
-  // under it — no extra .amalgm segment like project contexts have.
-  const root = path.join(path.resolve(AMALGM_DIR), 'context');
-  return { root, instructions: path.join(root, 'instructions.md') };
+  return systemContextPathsForAmalgmDir(AMALGM_DIR);
 }
 
 function isSystemProject(project) {
@@ -187,7 +190,7 @@ function readDoc(filePath) {
 }
 
 function statFingerprint(paths) {
-  return [paths.instructions, paths.changeLog, paths.projectState]
+  return [paths.instructions, paths.goals, paths.changeLog, paths.projectState]
     .filter(Boolean)
     .map((filePath) => {
       try {
@@ -235,11 +238,12 @@ function buildContextRecord(project) {
 
   const paths = contextPaths(project.path);
   const instructions = readDoc(paths.instructions);
+  const goals = readDoc(paths.goals);
   const changeLog = readDoc(paths.changeLog);
   const projectState = readDoc(paths.projectState);
   const latestEntry = latestChangeLogEntry(changeLog.content);
   const contextRevision = hash(
-    [instructions.revision, changeLog.revision, projectState.revision].join(':'),
+    [instructions.revision, goals.revision, changeLog.revision, projectState.revision].join(':'),
   ).slice(0, 20);
 
   return {
@@ -253,6 +257,7 @@ function buildContextRecord(project) {
     paths,
     files: {
       instructions: docMeta(instructions),
+      goals: docMeta(goals),
       changeLog: {
         ...docMeta(changeLog),
         latestEntryAt: latestEntry.iso,
@@ -262,6 +267,7 @@ function buildContextRecord(project) {
     },
     prompt: {
       instructions: instructions.empty ? '' : cappedDocContent(instructions.content),
+      goals: goals.empty ? '' : cappedDocContent(goals.content),
       projectState: projectState.empty ? '' : cappedDocContent(projectState.content),
       changeLogRecent: changeLog.empty ? '' : changeLogRecentWindow(changeLog.content),
     },
@@ -346,24 +352,40 @@ function reconcileProjectContext(input, options = {}) {
   return upsertContextRow(record, options);
 }
 
-const INSTRUCTIONS_TEMPLATE = `${INSTRUCTIONS_TITLE}\n`;
+const SYSTEM_INSTRUCTIONS_TEMPLATE = `${SYSTEM_INSTRUCTIONS_TITLE}\n`;
+const PROJECT_INSTRUCTIONS_TEMPLATE = `${PROJECT_INSTRUCTIONS_TITLE}\n`;
+const PROJECT_GOALS_TEMPLATE = `${PROJECT_GOALS_TITLE}\n`;
 const CHANGE_LOG_TEMPLATE = `${CHANGE_LOG_TITLE}\n`;
 const PROJECT_STATE_TEMPLATE = `${PROJECT_STATE_TITLE}\n`;
 
+function legacyInstructionsPath(paths) {
+  return path.join(paths.root, LEGACY_INSTRUCTIONS_FILENAME);
+}
+
+function writeInitialDoc(filePath, template, legacyPath = null) {
+  if (fs.existsSync(filePath)) return false;
+  if (legacyPath && fs.existsSync(legacyPath)) {
+    atomicWrite(filePath, fs.readFileSync(legacyPath, 'utf8'));
+  } else {
+    atomicWrite(filePath, template);
+  }
+  return true;
+}
+
 function ensureContextFiles(project) {
   const paths = contextPathsFor(project);
   const docs = isSystemProject(project)
-    ? [[paths.instructions, INSTRUCTIONS_TEMPLATE]]
+    ? [[paths.instructions, SYSTEM_INSTRUCTIONS_TEMPLATE, legacyInstructionsPath(paths)]]
     : [
-      [paths.instructions, INSTRUCTIONS_TEMPLATE],
-      [paths.changeLog, CHANGE_LOG_TEMPLATE],
+      [paths.instructions, PROJECT_INSTRUCTIONS_TEMPLATE, legacyInstructionsPath(paths)],
+      [paths.goals, PROJECT_GOALS_TEMPLATE],
       [paths.projectState, PROJECT_STATE_TEMPLATE],
+      [paths.changeLog, CHANGE_LOG_TEMPLATE],
     ];
   const created = [];
   fs.mkdirSync(paths.root, { recursive: true });
-  for (const [filePath, template] of docs) {
-    if (!fs.existsSync(filePath)) {
-      atomicWrite(filePath, template);
+  for (const [filePath, template, legacyPath] of docs) {
+    if (writeInitialDoc(filePath, template, legacyPath)) {
       created.push(filePath);
     }
   }
@@ -455,7 +477,7 @@ function appendChangeLog(inputPath, body, options = {}) {
     throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
   }
   if (isSystemProject(project)) {
-    throw new Error('The system context has instructions only — change logs are per-project.');
+    throw new Error('The system context has system-instructions.md only — change logs are per-project.');
   }
   const entryBody = sanitizeChangeLogBody(body);
   if (!entryBody) throw new Error('Change log entry body is required');
@@ -485,7 +507,7 @@ function writeContextDoc(inputPath, docKey, content, options = {}) {
     throw new Error(`No registered Amalgm project contains: ${cleanString(typeof inputPath === 'string' ? inputPath : inputPath?.path) || '(no path)'}`);
   }
   if (isSystemProject(project) && docKey !== 'instructions') {
-    throw new Error('The system context has instructions only — change logs and project state are per-project.');
+    throw new Error('The system context has system-instructions.md only — project goals, project state, and change logs are per-project.');
   }
   if (typeof content !== 'string') throw new Error('content must be a string');
   ensureContextFiles(project);
@@ -500,6 +522,13 @@ function writeContextDoc(inputPath, docKey, content, options = {}) {
   return { project, record };
 }
 
+/** project-goals.md: latest write wins; writable by UI and the memories tool. */
+function writeProjectGoals(inputPath, content, options = {}) {
+  return writeContextDoc(inputPath, 'goals', content, {
+    source: options.source || 'project-context:write-project-goals',
+  });
+}
+
 /** project-state.md: latest write wins; revision is metadata, not a lock. */
 function writeProjectState(inputPath, content, options = {}) {
   return writeContextDoc(inputPath, 'projectState', content, {
@@ -507,7 +536,7 @@ function writeProjectState(inputPath, content, options = {}) {
   });
 }
 
-/** instructions.md: user-authored; latest write wins via the UI path. */
+/** project/system instructions: user-authored; latest write wins via the UI path. */
 function writeInstructions(inputPath, content, options = {}) {
   return writeContextDoc(inputPath, 'instructions', content, {
     source: options.source || 'project-context:write-instructions',
@@ -667,5 +696,6 @@ module.exports = {
   watchProjectContext,
   writeChangeLog,
   writeInstructions,
+  writeProjectGoals,
   writeProjectState,
 };

package/runtime/scripts/amalgm-mcp/project-context/tools.js

@@ -72,6 +72,42 @@ module.exports = [
       }
     },
   },
+  {
+    name: 'write_project_goals',
+    description:
+      'Rewrite the active project\'s goals document (project-goals.md). Use this when durable goals, intended outcomes, success criteria, or explicit priorities have changed. Latest write wins; submit the COMPLETE new document as markdown. Keep goals distinct from progress: use project-state.md for current status and append_change_log for event history.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description: 'Full markdown content of the new project-goals.md (start with "# Project Goals").',
+        },
+        projectPath: PROJECT_PATH_INPUT,
+      },
+      required: ['content'],
+    },
+    async handler({ content, projectPath } = {}, context = {}) {
+      const target = targetPathFor({ projectPath }, context);
+      if (!target) return noProjectError('');
+      if (typeof content !== 'string' || !content.trim()) {
+        return errorResult('content is required (full markdown for project-goals.md)');
+      }
+      try {
+        const result = store.writeProjectGoals(target, content, {
+          source: 'project-context:tool',
+        });
+        return textResult(
+          `Project goals updated for ${result.project.name} (revision ${result.record?.files?.goals?.revision || 'unknown'}).\n`
+          + `File: ${result.record?.paths?.goals || ''}`,
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith('No registered Amalgm project')) return noProjectError(target);
+        return errorResult(message);
+      }
+    },
+  },
   {
     name: 'write_project_state',
     description:
@@ -111,7 +147,7 @@ module.exports = [
   {
     name: 'read_project_context',
     description:
-      'Read the active project\'s memory: instructions.md (user-authored), project-state.md (consolidated snapshot), and the recent change-log.md window (newest first). Use when you need to re-check project memory mid-session or inspect another project\'s context via projectPath.',
+      'Read the active project\'s memory: project-instructions.md (user-authored), project-goals.md (intended outcomes), project-state.md (consolidated snapshot), and the recent change-log.md window (newest first). Use when you need to re-check project memory mid-session or inspect another project\'s context via projectPath.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -128,9 +164,12 @@ module.exports = [
           `Project: ${record.name} (${record.projectPath})`,
           `Context revision: ${record.contextRevision}`,
           '',
-          '## instructions.md',
+          '## project-instructions.md',
           record.prompt?.instructions || '(empty)',
           '',
+          '## project-goals.md',
+          record.prompt?.goals || '(empty)',
+          '',
           '## project-state.md',
           record.prompt?.projectState || '(empty)',
           '',

package/runtime/scripts/amalgm-mcp/server/core-tools.js

@@ -43,7 +43,7 @@ const CORE_TOOL_GROUPS = [
   group(
     'memories',
     'Memories',
-    'Maintain project memory: append change-log entries and keep the project-state snapshot current.',
+    'Maintain project memory: append change-log entries and keep project goals/state current.',
     require('../project-context/tools'),
   ),
   group(

package/runtime/scripts/amalgm-mcp/server/routes/project-context.js

@@ -23,6 +23,10 @@ async function handleProjectContextRoutes(ctx) {
     await projectContextRest.handleWriteProjectState(await ctx.readJsonBody(), ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/project-context/project-goals' && ctx.method === 'PUT') {
+    await projectContextRest.handleWriteProjectGoals(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   if (ctx.pathname === '/project-context/instructions' && ctx.method === 'PUT') {
     await projectContextRest.handleWriteInstructions(await ctx.readJsonBody(), ctx.sendJson);
     return true;

package/runtime/scripts/amalgm-mcp/tests/core-tools.test.js

@@ -27,6 +27,7 @@ test('core tool grouping preserves handler definitions for MCP surface wrapping'
   assert.equal(CORE_TOOLS.some((tool) => tool.name === 'open' && tool.toolboxToolId === 'browser'), true);
   assert.equal(CORE_TOOLS.some((tool) => tool.name === 'notify_user'), true);
   assert.equal(CORE_TOOLS.some((tool) => tool.name === 'append_change_log'), true);
+  assert.equal(CORE_TOOLS.some((tool) => tool.name === 'write_project_goals'), true);
 });
 
 test('core tool actions carry stable toolbox ids', () => {

package/runtime/scripts/amalgm-mcp/tests/project-context.test.js

@@ -41,7 +41,7 @@ test.after(() => {
   fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
-test('ensureProjectContext creates the three docs and a row, additively', () => {
+test('ensureProjectContext creates project docs and a row, additively', () => {
   const { projectPath, workspace } = makeProject('ensure');
   const preexisting = path.join(projectPath, 'keep.txt');
   fs.writeFileSync(preexisting, 'keep me');
@@ -50,15 +50,27 @@ test('ensureProjectContext creates the three docs and a row, additively', () =>
 
   assert.deepEqual(
     fs.readdirSync(path.join(projectPath, '.amalgm', 'context')).sort(),
-    ['change-log.md', 'instructions.md', 'project-state.md'],
+    ['change-log.md', 'project-goals.md', 'project-instructions.md', 'project-state.md'],
   );
   assert.equal(fs.readFileSync(preexisting, 'utf8'), 'keep me');
   assert.equal(record.projectId, workspace.id);
   assert.ok(record.contextRevision);
   // Existing content is never clobbered by a second ensure.
-  fs.writeFileSync(path.join(projectPath, '.amalgm/context/instructions.md'), '# Instructions\n\nKeep these.\n');
+  fs.writeFileSync(path.join(projectPath, '.amalgm/context/project-instructions.md'), '# Project Instructions\n\nKeep these.\n');
   store.ensureProjectContext(workspace, { source: 'test' });
-  assert.match(readContextFile(projectPath, 'instructions.md'), /Keep these\./);
+  assert.match(readContextFile(projectPath, 'project-instructions.md'), /Keep these\./);
+});
+
+test('ensureProjectContext migrates legacy instructions.md without deleting it', () => {
+  const { projectPath, workspace } = makeProject('legacy-instructions');
+  const contextDir = path.join(projectPath, '.amalgm', 'context');
+  fs.mkdirSync(contextDir, { recursive: true });
+  fs.writeFileSync(path.join(contextDir, 'instructions.md'), '# Instructions\n\nLegacy project guidance.\n');
+
+  store.ensureProjectContext(workspace, { source: 'test' });
+
+  assert.match(readContextFile(projectPath, 'project-instructions.md'), /Legacy project guidance\./);
+  assert.match(readContextFile(projectPath, 'instructions.md'), /Legacy project guidance\./);
 });
 
 test('appendChangeLog stamps runtime timestamps and prepends under the title', () => {
@@ -115,6 +127,23 @@ test('writeProjectState is latest-write-wins with revision metadata', () => {
   assert.notEqual(first.record.contextRevision, second.record.contextRevision);
 });
 
+test('writeProjectGoals is latest-write-wins and separate from project state', () => {
+  const { projectPath, workspace } = makeProject('goals');
+  store.ensureProjectContext(workspace);
+
+  const first = store.writeProjectGoals(projectPath, '# Project Goals\n\nDraft goal.');
+  const second = store.writeProjectGoals(projectPath, '# Project Goals\n\nFinal goal.');
+  const record = store.getProjectContext(projectPath, { reconcile: false });
+
+  assert.equal(readContextFile(projectPath, 'project-goals.md'), '# Project Goals\n\nFinal goal.\n');
+  assert.equal(record.prompt.goals.includes('Final goal.'), true);
+  assert.equal(record.prompt.projectState, '');
+  assert.notEqual(
+    first.record.files.goals.revision,
+    second.record.files.goals.revision,
+  );
+});
+
 test('reconcile is idempotent and catches out-of-band edits', () => {
   const { projectPath, workspace } = makeProject('reconcile');
   store.ensureProjectContext(workspace);
@@ -180,14 +209,17 @@ test('fresh threads get the full prompt block; resumed threads get deltas', asyn
   const { projectPath, workspace } = makeProject('prompt');
   store.ensureProjectContext(workspace);
   store.appendChangeLog(projectPath, '- Completed: baseline work.');
+  store.writeProjectGoals(projectPath, '# Project Goals\n\nShip the memory system.');
   store.writeProjectState(projectPath, '# Project State\n\nBaseline state.');
 
   const fresh = { sessionId: 'sess-prompt', cwd: projectPath, providerSessionId: null };
   const block = prompt.projectContextPromptBlock(fresh);
   assert.ok(block.includes('<project_context>'));
   assert.ok(block.includes('Baseline state.'));
+  assert.ok(block.includes('Ship the memory system.'));
   assert.ok(block.includes('baseline work.'));
   assert.ok(block.includes('toolbox__memories_append_change_log'));
+  assert.ok(block.includes('toolbox__memories_write_project_goals'));
   // Empty instructions are omitted entirely.
   assert.ok(!block.includes('<project_instructions'));
 
@@ -201,8 +233,16 @@ test('fresh threads get the full prompt block; resumed threads get deltas', asyn
   assert.ok(update.includes('<project_context_update>'));
   assert.ok(update.includes('same-second follow-up.'));
   assert.ok(!update.includes('Baseline state.'), 'unchanged state stays out of the delta');
+  assert.ok(!update.includes('Ship the memory system.'), 'unchanged goals stay out of the delta');
   assert.equal(prompt.projectContextTurnUpdateBlock(resumed), '', 'update settles');
 
+  // Goals rewrite -> full new goals in the delta.
+  store.writeProjectGoals(projectPath, '# Project Goals\n\nLaunch project memory.');
+  const goalsUpdate = prompt.projectContextTurnUpdateBlock(resumed);
+  assert.ok(goalsUpdate.includes('<project_goals'));
+  assert.ok(goalsUpdate.includes('Launch project memory.'));
+  assert.ok(!goalsUpdate.includes('new_change_log_entries'));
+
   // State rewrite -> full new state in the delta.
   store.writeProjectState(projectPath, '# Project State\n\nNew state.');
   const stateUpdate = prompt.projectContextTurnUpdateBlock(resumed);
@@ -235,8 +275,13 @@ test('memories tools resolve the session project and enforce registration', asyn
   const wrote = await byName.write_project_state.handler({ content: '# Project State\n\nTool state.' }, context);
   assert.ok(!wrote.isError);
 
+  const goals = await byName.write_project_goals.handler({ content: '# Project Goals\n\nTool goals.' }, context);
+  assert.ok(!goals.isError);
+  assert.ok(readContextFile(projectPath, 'project-goals.md').includes('Tool goals.'));
+
   const read = await byName.read_project_context.handler({}, context);
   assert.ok(read.content[0].text.includes('Tool state.'));
+  assert.ok(read.content[0].text.includes('Tool goals.'));
 
   const missing = await byName.append_change_log.handler({ body: '- x' }, { callerSessionId: 'no-cwd' });
   assert.ok(missing.isError);
@@ -245,7 +290,7 @@ test('memories tools resolve the session project and enforce registration', asyn
 
 test('system scope: instructions-only record, guarded writes, canonical save path', () => {
   const systemContextDir = path.join(process.env.AMALGM_DIR, 'context');
-  const systemInstructionsPath = path.join(systemContextDir, 'instructions.md');
+  const systemInstructionsPath = path.join(systemContextDir, 'system-instructions.md');
 
   // The boot pass owns file creation for the system scope.
   store.startProjectContextService();
@@ -258,17 +303,18 @@ test('system scope: instructions-only record, guarded writes, canonical save pat
   assert.equal(system.name, 'Amalgm System');
   assert.equal(system.paths.instructions, systemInstructionsPath);
   assert.equal(system.paths.changeLog, undefined, 'system has no change log');
+  assert.equal(system.paths.goals, undefined, 'system has no project goals');
   assert.equal(system.files.projectState, undefined, 'system has no project state');
   assert.ok(fs.existsSync(systemInstructionsPath), 'boot/list ensured the file');
   assert.deepEqual(
     fs.readdirSync(systemContextDir).filter((name) => name.endsWith('.md')).sort(),
-    ['instructions.md'],
-    'only instructions.md is created for the system scope',
+    ['system-instructions.md'],
+    'only system-instructions.md is created for the system scope',
   );
 
   // The UI editor saves by file path — it must resolve to the system scope.
   const before = currentSeq();
-  const written = store.writeInstructions(systemInstructionsPath, '# Instructions\n\nAlways be definitive.');
+  const written = store.writeInstructions(systemInstructionsPath, '# System Instructions\n\nAlways be definitive.');
   assert.equal(written.project.id, 'system');
   const events = listEventsAfter(before).filter((event) => event.resource === 'project_context');
   assert.equal(events.length, 1);
@@ -276,23 +322,25 @@ test('system scope: instructions-only record, guarded writes, canonical save pat
   assert.ok(events[0].value.prompt.instructions.includes('Always be definitive.'));
 
   // System scope rejects per-project docs.
-  assert.throws(() => store.appendChangeLog(systemInstructionsPath, '- x'), /instructions only/);
-  assert.throws(() => store.writeProjectState(systemContextDir, '# Project State'), /instructions only/);
+  assert.throws(() => store.appendChangeLog(systemInstructionsPath, '- x'), /system-instructions\.md only/);
+  assert.throws(() => store.writeProjectGoals(systemContextDir, '# Project Goals'), /system-instructions\.md only/);
+  assert.throws(() => store.writeProjectState(systemContextDir, '# Project State'), /system-instructions\.md only/);
 });
 
 test('system instructions prompt block reads the canonical file', () => {
   const { systemInstructionsBlock, systemInstructionsPath } = require('../../chat-core/tooling/system-instructions');
   const filePath = systemInstructionsPath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
 
-  fs.writeFileSync(filePath, '# Instructions\n\nNo instructions for Amalgm System yet.\n');
+  fs.writeFileSync(filePath, '# System Instructions\n\nNo instructions for Amalgm System yet.\n');
   assert.equal(systemInstructionsBlock(), '', 'legacy placeholder counts as empty');
 
-  fs.writeFileSync(filePath, '# Instructions\n\nPrefer pnpm everywhere.\n');
+  fs.writeFileSync(filePath, '# System Instructions\n\nPrefer pnpm everywhere.\n');
   const block = systemInstructionsBlock();
   assert.ok(block.includes('<system_instructions'));
   assert.ok(block.includes('Prefer pnpm everywhere.'));
 
-  fs.writeFileSync(filePath, '# Instructions\n');
+  fs.writeFileSync(filePath, '# System Instructions\n');
   assert.equal(systemInstructionsBlock(), '', 'blank doc injects nothing');
 });
 

package/runtime/scripts/chat-core/tooling/system-instructions.js

@@ -3,20 +3,22 @@
 /**
  * System-level instructions — the one machine-wide context doc.
  *
- * `<AMALGM_DIR>/context/instructions.md` is user-authored and applies to every
- * session on this computer. Project memory (instructions, change log, project
- * state) is handled separately by the project-context block. The legacy
- * active/passive memory blocks are gone — this and project context are the
- * definitive memory surfaces.
+ * `<AMALGM_DIR>/context/system-instructions.md` is user-authored and applies
+ * to every session on this computer. Project memory is handled separately by
+ * the project-context block. The legacy active/passive memory blocks are gone
+ * — this and project context are the definitive memory surfaces.
  */
 
 const fs = require('fs');
-const path = require('path');
 const { AMALGM_DIR } = require('../../amalgm-mcp/config');
-const { cappedDocContent, isEmptyContextDoc } = require('../../amalgm-mcp/project-context/paths');
+const {
+  cappedDocContent,
+  isEmptyContextDoc,
+  systemContextPaths,
+} = require('../../amalgm-mcp/project-context/paths');
 
 function systemInstructionsPath() {
-  return path.join(path.resolve(AMALGM_DIR), 'context', 'instructions.md');
+  return systemContextPaths(AMALGM_DIR).instructions;
 }
 
 function escapeAttribute(value) {

package/runtime/scripts/chat-core/tooling/system-prompt.js

@@ -33,9 +33,10 @@ function systemInstructionsBlockSafe() {
 
 /**
  * Definitive memory model: platform context, system instructions
- * (machine-wide, user-authored), project context (instructions + project
- * state + recent change log, maintained through the memories tool), and the
- * agent's own instructions. The legacy active/passive memory blocks are gone.
+ * (machine-wide, user-authored), project context (project instructions +
+ * goals + state + recent change log, maintained through the memories tool),
+ * and the agent's own instructions. The legacy active/passive memory blocks
+ * are gone.
  */
 function composeSystemPrompt(contract) {
   const parts = [];