@limina-labs/momentum 0.34.0 → 0.36.0

package/adapters/antigravity/instructions/AGENTS.md

@@ -176,6 +176,10 @@ lives in this AGENTS.md primary-instruction text as a belt-and-braces
 fallback: if a `.momentum/inbox/handoff-NNN.md` file exists at session
 start, read it and acknowledge before continuing.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Antigravity's task tool is the native **task list** artifact (task.md) — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -197,7 +201,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the native **task list** artifact (task.md) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -215,7 +219,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The task-list artifact is enough" — The task-list artifact is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries
@@ -638,6 +642,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/antigravity/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "antigravity",
+  "displayName": "Antigravity",
+  "surface": "agents-md",
+  "taskTool": "the native **task list** artifact (task.md)",
+  "taskToolName": "The task-list artifact",
+  "hasSurfaceDelta": true
+}

package/adapters/claude-code/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "claude-code",
+  "displayName": "Claude Code",
+  "surface": "claude-md",
+  "taskTool": "the built-in **TodoWrite** tool",
+  "taskToolName": "TodoWrite",
+  "hasSurfaceDelta": false
+}

package/adapters/codex/instructions/AGENTS.md

@@ -48,7 +48,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |
@@ -230,6 +230,10 @@ This is the documented escalation point referenced in Phase 18 G1
 plan.md; if the MCP shim is widely broken, momentum will ship a
 minimal `core/swarm/mcp-cwd-server.js` in a follow-up.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Codex's task tool is the built-in **plan** tool — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -251,7 +255,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **plan** tool to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -269,7 +273,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The plan tool is enough" — The plan tool is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries
@@ -692,6 +696,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/codex/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "codex",
+  "displayName": "Codex",
+  "surface": "agents-md",
+  "taskTool": "the built-in **plan** tool",
+  "taskToolName": "The plan tool",
+  "hasSurfaceDelta": true
+}

package/adapters/codex/instructions/surfaces.md

@@ -24,7 +24,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/adapters/opencode/instructions/AGENTS.md

@@ -48,7 +48,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |
@@ -143,6 +143,10 @@ skill paths (`.claude/skills/`, `.agents/skills/`); momentum's opencode
 surfaces live under `.opencode/` so multi-adapter installs stay
 side-by-side without collisions.
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), opencode's task tool is the built-in **task** tool (subagent fan-out) — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -164,7 +168,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **task** tool (subagent fan-out) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -182,7 +186,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "The task tool is enough" — The task tool is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries
@@ -605,6 +609,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/adapters/opencode/instructions/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "opencode",
+  "displayName": "opencode",
+  "surface": "agents-md",
+  "taskTool": "the built-in **task** tool (subagent fan-out)",
+  "taskToolName": "The task tool",
+  "hasSurfaceDelta": true
+}

package/adapters/opencode/instructions/surfaces.md

@@ -24,7 +24,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
-| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062) |
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/bin/ecosystem.js

@@ -24,8 +24,11 @@ const {
   POINTER_END,
   PRIMARY_INSTRUCTION_CANDIDATES,
   findPrimaryInstructionFile,
+  findAllInstructionFiles,
   ensurePointerInjected,
+  ensurePointerInjectedAll,
   stripPointer,
+  stripPointerAll,
 } = require('../core/ecosystem/lib/pointer');
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -616,7 +619,7 @@ function cmdAdd(args) {
     // Idempotent: if the path matches, do nothing. If it differs, fail loud.
     if (existing.path === relPath) {
       console.log(`add: "${id}" is already registered (path ${relPath}). No changes.`);
-      ensurePointerInjected(absRepo, primary, root, manifest.name);
+      ensurePointerInjectedAll(absRepo, root, manifest.name);
       return;
     }
     throw new Error(
@@ -641,11 +644,12 @@ function cmdAdd(args) {
     'utf8',
   );
 
-  // Inject the fenced pointer into the target's primary instruction.
-  ensurePointerInjected(absRepo, primary, root, manifest.name);
+  // Inject the fenced pointer into EVERY instruction file (Phase 28 — every
+  // agent, not just the preferred one).
+  const injected = ensurePointerInjectedAll(absRepo, root, manifest.name);
 
   console.log(`Added member "${id}" (${role}) at ${relPath}.`);
-  console.log(`Pointer injected into ${path.relative(root, path.join(absRepo, primary))}.`);
+  console.log(`Pointer injected into ${injected.map((f) => path.relative(root, path.join(absRepo, f))).join(', ')}.`);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -686,10 +690,7 @@ function cmdRemove(args) {
   // remove must succeed even when the member repo is gone.
   const absRepo = path.resolve(root, member.path);
   if (fs.existsSync(absRepo)) {
-    const primary = findPrimaryInstructionFile(absRepo);
-    if (primary) {
-      stripPointer(path.join(absRepo, primary));
-    }
+    stripPointerAll(absRepo); // Phase 28 — strip from every instruction file
   }
 
   console.log(`Removed member "${id}".`);
@@ -776,9 +777,18 @@ function detectMemberAgent(repoPath) {
     const m = JSON.parse(
       fs.readFileSync(path.join(repoPath, '.momentum', 'installed.json'), 'utf8'),
     );
-    if (m && m.agent) return m.agent;
+    // ADR-0007: the lock is `{ agents: { <id>: … } }`; the pre-0007 lock was
+    // `{ agent }`. Read the map first (else every AGENTS.md agent — opencode,
+    // Antigravity, Codex — falls through to the `AGENTS.md ⇒ codex` heuristic
+    // below and is misidentified). ADR-0011.
+    if (m && m.agents && typeof m.agents === 'object') {
+      const ids = Object.keys(m.agents);
+      if (ids.length) return ids.includes('claude-code') ? 'claude-code' : ids.sort()[0];
+    }
+    if (m && m.agent) return m.agent; // legacy single-agent lock
   } catch (_e) { /* fall through to heuristic */ }
   if (fs.existsSync(path.join(repoPath, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(repoPath, '.opencode'))) return 'opencode';
   if (fs.existsSync(path.join(repoPath, '.claude'))) return 'claude-code';
   if (
     fs.existsSync(path.join(repoPath, '.agents', 'hooks.json')) ||
@@ -1296,6 +1306,7 @@ module.exports = {
   ensurePointerInjected,
   stripPointer,
   findPrimaryInstructionFile,
+  detectMemberAgent,
   sanitizeId,
   POINTER_BEGIN,
   POINTER_END,

package/bin/momentum.js

@@ -719,7 +719,46 @@ function resolveAdapterSource(srcRoot, adapterDir, fileSpec) {
   return path.join(base, ...fileSpec.source);
 }
 
-function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction) {
+/**
+ * ADR-0011 — the raw primary-instruction template content for `agent`.
+ * A claude-md agent (and a lone installed agents-md agent) gets the static
+ * committed template. When MORE THAN ONE agents-md agent is installed, AGENTS.md
+ * is COMPOSED — the neutral spine once + one integration section per installed
+ * AGENTS.md agent — so switching or running several agents never drops an
+ * integration (fixes the same-path collision). Project name is not yet rendered.
+ */
+function resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath) {
+  const readStatic = () => fs.readFileSync(srcPath, 'utf8');
+  let compose;
+  try {
+    compose = require('../core/lib/instruction-compose');
+  } catch (_e) {
+    return readStatic();
+  }
+  let manifest;
+  try {
+    manifest = compose.readManifest(srcRoot, agent);
+  } catch (_e) {
+    return readStatic(); // unknown / manifest-less agent → static template
+  }
+  if (manifest.surface !== 'agents-md') return readStatic(); // claude-md → static
+
+  // The set of installed AGENTS.md agents ∪ the one being (re)installed.
+  const valid = new Set(compose.discoverAgents(srcRoot));
+  const ids = new Set(valid.has(agent) ? [agent] : []);
+  const state = loadInstalledState(targetDir);
+  for (const id of Object.keys(state.agents || {})) {
+    if (!valid.has(id)) continue;
+    try {
+      if (compose.readManifest(srcRoot, id).surface === 'agents-md') ids.add(id);
+    } catch (_e) { /* skip an agent we can't read */ }
+  }
+  const sorted = [...ids].sort();
+  if (sorted.length <= 1) return readStatic(); // N=1 → static committed template
+  return compose.composeInstruction(srcRoot, sorted); // N>1 → composed
+}
+
+function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction, agent) {
   if (!primaryInstruction) return null;
   const srcPath = resolveAdapterSource(srcRoot, adapterDir, primaryInstruction);
   const destPath = path.join(targetDir, ...primaryInstruction.destination);
@@ -733,7 +772,7 @@ function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
       return 'added';
     }
     const rendered = renderProjectName(
-      fs.readFileSync(srcPath, 'utf8'),
+      resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath),
       getProjectName(targetDir)
     );
     fs.mkdirSync(path.dirname(destPath), { recursive: true });
@@ -745,7 +784,7 @@ function installPrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
   return 'skipped';
 }
 
-function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction) {
+function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstruction, agent) {
   if (!primaryInstruction) return null;
   const srcPath = resolveAdapterSource(srcRoot, adapterDir, primaryInstruction);
   const destPath = path.join(targetDir, ...primaryInstruction.destination);
@@ -753,12 +792,15 @@ function upgradePrimaryInstruction(srcRoot, targetDir, adapterDir, primaryInstru
   const projectName = getProjectName(targetDir);
   recordManaged(destPath); // managed (marker-owned)
 
+  // ADR-0011: compose AGENTS.md across all installed AGENTS.md agents.
+  const rawContent = resolvePrimaryInstructionContent(srcRoot, targetDir, agent, srcPath);
+
   console.log(`→ Upgrading ${label}...`);
   if (primaryInstruction.markerAware) {
-    return upgradeMarkedFile(srcPath, destPath, label, targetDir, projectName);
+    return upgradeMarkedFile(srcPath, destPath, label, targetDir, projectName, rawContent);
   }
 
-  const srcContent = renderProjectName(fs.readFileSync(srcPath, 'utf8'), projectName);
+  const srcContent = renderProjectName(rawContent, projectName);
   const relDest = path.relative(targetDir, destPath);
   if (!fileExists(destPath)) {
     if (_dryRun) {
@@ -895,11 +937,14 @@ function partitionByMarker(content) {
  *
  * Returns one of: 'added', 'updated', 'unchanged', 'migrated'.
  */
-function upgradeMarkedFile(srcPath, destPath, label, root, projectName) {
+function upgradeMarkedFile(srcPath, destPath, label, root, projectName, srcContentRaw) {
   const rel = path.relative(root || process.cwd(), destPath);
   recordManaged(destPath); // managed (marker-owned) in all branches
   const render = (content) =>
     projectName ? renderProjectName(content, projectName) : content;
+  // ADR-0011: callers may pass composed content (multi-agent AGENTS.md); else
+  // read the static committed template.
+  const rawSrc = srcContentRaw != null ? srcContentRaw : fs.readFileSync(srcPath, 'utf8');
 
   if (!fileExists(destPath)) {
     if (_dryRun) {
@@ -907,12 +952,12 @@ function upgradeMarkedFile(srcPath, destPath, label, root, projectName) {
       return 'added';
     }
     fs.mkdirSync(path.dirname(destPath), { recursive: true });
-    fs.writeFileSync(destPath, render(fs.readFileSync(srcPath, 'utf8')));
+    fs.writeFileSync(destPath, render(rawSrc));
     console.log(`  + added:    ${rel}`);
     return 'added';
   }
 
-  const srcContent = render(fs.readFileSync(srcPath, 'utf8'));
+  const srcContent = render(rawSrc);
   const destContent = fs.readFileSync(destPath, 'utf8');
   const destParts = partitionByMarker(destContent);
 
@@ -1215,7 +1260,7 @@ function init(targetDir, agent, opts = {}) {
   console.log('→ Inferring project config...');
   installConfig(target, { dryRun: _dryRun });
 
-  installPrimaryInstruction(src, target, adapterDir, adapter.primaryInstruction);
+  installPrimaryInstruction(src, target, adapterDir, adapter.primaryInstruction, agent);
 
   // Adapter overlay — per-agent commands/agent-rules/scripts (additive)
   applyOverlay(adapterDir, target, dests, { backup: true, root: target });
@@ -1348,11 +1393,32 @@ function upgrade(targetDir, agent, opts = {}) {
   // would dirty files mid-upgrade and break autostash restores).
   const pointerLib = require('../core/ecosystem/lib/pointer');
   const primaryRel = adapter.primaryInstruction.destination.join('/');
+
+  // Phase 28 (ADR-0010): migrate any authored `## Project Extensions` prose into
+  // specs/project-rules.md and rewrite that section as the managed pointer,
+  // BEFORE the marker-aware rewrite preserves it. Migrate-never-drop, idempotent.
+  if (!_dryRun) {
+    const projectRules = require('../core/lib/project-rules');
+    const migRes = projectRules.migrateProjectExtensions(
+      path.join(target, primaryRel),
+      path.join(target, 'specs'),
+      { projectName: getProjectName(target) }
+    );
+    if (migRes.appended) {
+      console.log(`  ↳ migrated ${primaryRel} Project Extensions → specs/project-rules.md (ADR-0010)`);
+    }
+  }
+
+  // Snapshot whether THIS agent's instruction file carries the pointer BEFORE
+  // the managed rewrite — we only ever PRESERVE it (BUG-022), never add one the
+  // file didn't have (adding would dirty files mid-upgrade and break autostash
+  // restores). Phase 28: since `upgrade` now runs per installed agent (G1), this
+  // preserves every agent's pointer; ADDING a missing pointer (cause #2) is
+  // `momentum ecosystem add`'s job, which now injects into all instruction files.
   let hadPointerBlock = false;
   try {
-    hadPointerBlock = pointerLib.POINTER_BEGIN_RE.test(
-      fs.readFileSync(path.join(target, primaryRel), 'utf8')
-    );
+    hadPointerBlock = fs.readFileSync(path.join(target, primaryRel), 'utf8')
+      .includes(pointerLib.POINTER_BEGIN_PREFIX);
   } catch (_e) { /* absent file → nothing to preserve */ }
 
   // Upgrade adapter-owned root instruction file
@@ -1360,7 +1426,8 @@ function upgrade(targetDir, agent, opts = {}) {
     src,
     target,
     adapterDir,
-    adapter.primaryInstruction
+    adapter.primaryInstruction,
+    agent
   );
 
   if (hadPointerBlock && !_dryRun) {
@@ -1983,12 +2050,27 @@ async function main() {
       // upgrade can only ever install files as new as the CLI itself.
       const staleWarning = formatStaleCliWarning(pkg.version, await updateCheckPromise);
       if (staleWarning) console.log(staleWarning);
-      // --autostash: stash a dirty tree, upgrade, restore. Dry-run writes
-      // nothing, so it never needs to stash.
+      // Phase 28 (ADR-0010): with no explicit --agent, refresh EVERY installed
+      // agent so no agent's instruction file silently drifts (cause #1 of the
+      // CLAUDE.md/AGENTS.md divergence). Explicit --agent targets that one.
+      let agentsToUpgrade;
+      if (agentExplicit) {
+        agentsToUpgrade = [agent];
+      } else {
+        const installed = loadInstalledState(path.resolve(targetDir));
+        const names = Object.keys(installed.agents || {});
+        agentsToUpgrade = names.length ? names : [agent];
+      }
+      if (agentsToUpgrade.length > 1) {
+        console.log(`Upgrading all installed agents: ${agentsToUpgrade.join(', ')}\n`);
+      }
+      // --autostash: stash a dirty tree, upgrade, restore — once around all
+      // agents. Dry-run writes nothing, so it never needs to stash.
+      const runAll = () => { for (const a of agentsToUpgrade) upgrade(targetDir, a, { dryRun }); };
       if (autostash && !dryRun) {
-        withAutostash(path.resolve(targetDir), () => upgrade(targetDir, agent, { dryRun }));
+        withAutostash(path.resolve(targetDir), runAll);
       } else {
-        upgrade(targetDir, agent, { dryRun });
+        runAll();
       }
     } catch (err) {
       console.error(`\nError: ${err.message}`);

package/bin/state-commands.js

@@ -103,10 +103,9 @@ function cmdLeave(args) {
   }
 
   if (state === 'broken-pointer') {
-    // Pointer present but no registration. Just strip pointer to recover.
-    const primary = pointerLib.findPrimaryInstructionFile(cwd);
-    if (primary) {
-      pointerLib.stripPointer(path.join(cwd, primary));
+    // Pointer present but no registration. Strip from every instruction file.
+    const stripped = pointerLib.stripPointerAll(cwd);
+    if (stripped.length) {
       console.log('Stripped dangling pointer. Now standalone.');
     } else {
       console.log('No pointer block found. No changes.');

package/core/commands/complete-phase.md

@@ -89,7 +89,7 @@ Verify, finalize, and release a completed phase.
    `[staging, main]`) in order. The plan stops at the universal git primitives
    (`git merge` + `git tag -a` + `git push origin <tag>`); forge-specific
    release creation and registry publishes are NOT listed here — they run
-   from `## Project Extensions` + `specs/config.md` (`release_command`,
+   from `specs/project-rules.md` + `specs/config.md` (`release_command`,
    `publish_target`, `release_flow`) after the tag is pushed.
    ```
    Ready to release vX.Y.Z. This will:
@@ -98,7 +98,7 @@ Verify, finalize, and release a completed phase.
      3. Tag vX.Y.Z and push the tag
 
    Project-specific release/publish/deploy (forge release, npm publish, …)
-   run from ## Project Extensions + specs/config.md after the tag lands.
+   run from specs/project-rules.md + specs/config.md after the tag lands.
 
    Proceed?
    ```
@@ -126,7 +126,7 @@ Verify, finalize, and release a completed phase.
     git push origin <branch_flow[1]>
 
     # final step — tag + push the tag (universal git; forge release + publish
-    # are project-specific — run them from ## Project Extensions now)
+    # are project-specific — run them from specs/project-rules.md now)
     git tag -a vX.Y.Z -m "Phase N: {phase name}"
     git push origin vX.Y.Z
     ```
@@ -154,7 +154,7 @@ Verify, finalize, and release a completed phase.
 12. Report summary to user:
     - What was delivered
     - Tag URL (`git push origin vX.Y.Z` output) — forge release/publish
-      status from `## Project Extensions` if any ran
+      status from `specs/project-rules.md` if any ran
     - What's next
 
 13. Clean up the spent phase branch (ENH-042 / BUG-026 — now that merge → main

package/core/commands/start-phase.md

@@ -153,14 +153,14 @@ defaults below) and ask the user the gate question matching the project's
   reconcile --execute` cleans up the branch + worktree + state."
 
 Then append: "Project-specific release/publish/deploy steps (e.g.
-`npm publish`, forge release creation) run from `## Project Extensions` in
+`npm publish`, forge release creation) run from `specs/project-rules.md` in
 CLAUDE.md/AGENTS.md — consult them now if any apply."
 
 The gate stops at the truly universal git primitives — `git merge` +
 `git tag -a` + `git push origin <tag>`. Forge-specific release creation
 (`gh release create`, `glab release create`, …) and registry publishes
 (`npm publish`, `twine upload`, …) are NOT in this template; they live in
-`## Project Extensions` + `specs/config.md` (`release_command`,
+`specs/project-rules.md` + `specs/config.md` (`release_command`,
 `publish_target`, `release_flow`).
 
 This is the only place the engine asks. Do NOT skip it.

package/core/commands/start-project.md

@@ -79,15 +79,14 @@ If you're still exploring the idea, run `/brainstorm-idea` first.
    - `specs/planning/roadmap.md`
    - `specs/config.md` (from the config table above; overwrite the
      `momentum init`-inferred file if present — founding owns the content)
+   - `specs/project-rules.md` (project-specific prose rules; each instruction
+     file's `## Project Extensions` points here — ADR-0010)
    - Update `specs/status.md`: Summary, Current Phase (Phase 0 `not started`),
      Upcoming Phases, Next Actions
    - For monorepo: `specs/architecture/` first-pass doc(s)
    - `specs/phases/phase-0-shortname/{overview,plan,tasks,history}.md`
      (log the founding decisions from this conversation in `history.md`)
-   - Refresh the derived cache: `core/config.js` →
-     `writeConfigCache('.', readConfig('specs'))` so the pre-push
-     hook's `protected_branches` matches the authored `branch_flow`;
-     then `momentum okf index` to refresh bundle listings
+   - Refresh derived cache (`writeConfigCache`) + `momentum okf index`
 
 7. Commit the founding:
     ```bash

package/core/commands/validate.md

@@ -30,6 +30,9 @@ Run with no arguments for a fast index-first check, or pass `--deep` for a full
    - Not founded with no phase directories is the VALID Installed state —
      report informationally ("not founded yet — `/start-project` when
      ready"), never as a failure
+   - founded AND no `specs/project-rules.md` (ADR-0010) → WARNING: "project
+     rules surface missing — run `momentum upgrade` to create it; every agent
+     instruction file's `## Project Extensions` pointer expects it"
 
 2c. Config (ADR-0009) — WARNING, never a failure (recipes fall back to
     npm/GitHub defaults when absent):

package/core/ecosystem/lib/pointer.js

@@ -159,6 +159,45 @@ function ensurePointerInjected(absRepo, primaryFile, root, ecosystemName) {
   fs.writeFileSync(filePath, next, 'utf8');
 }
 
+/**
+ * All present primary instruction files in a member repo (not just the first).
+ * Phase 28 (ADR-0010): the ecosystem pointer must reach EVERY agent's file, so
+ * a Codex/opencode session reading AGENTS.md is not blind to the ecosystem.
+ */
+function findAllInstructionFiles(repoPath) {
+  return PRIMARY_INSTRUCTION_CANDIDATES.filter((name) =>
+    fs.existsSync(path.join(repoPath, name)));
+}
+
+/**
+ * Inject/refresh the pointer block in EVERY present instruction file
+ * (Phase 28). Returns the list of files touched. When none exist, returns [].
+ */
+function ensurePointerInjectedAll(absRepo, root, ecosystemName) {
+  const files = findAllInstructionFiles(absRepo);
+  for (const primaryFile of files) {
+    ensurePointerInjected(absRepo, primaryFile, root, ecosystemName);
+  }
+  return files;
+}
+
+/**
+ * Strip the pointer block from EVERY present instruction file (Phase 28).
+ * Returns only the files that actually HAD a pointer (so callers can report
+ * "nothing to strip" accurately).
+ */
+function stripPointerAll(absRepo) {
+  const stripped = [];
+  for (const primaryFile of findAllInstructionFiles(absRepo)) {
+    const fp = path.join(absRepo, primaryFile);
+    let had = false;
+    try { had = fs.readFileSync(fp, 'utf8').includes(POINTER_BEGIN_PREFIX); } catch { /* absent */ }
+    stripPointer(fp);
+    if (had) stripped.push(primaryFile);
+  }
+  return stripped;
+}
+
 /**
  * Strip the pointer block (any version) and one surrounding blank
  * line from the given file. Idempotent: silently no-ops if the file
@@ -191,8 +230,11 @@ module.exports = {
   POINTER_BLOCK_RE,
   PRIMARY_INSTRUCTION_CANDIDATES,
   findPrimaryInstructionFile,
+  findAllInstructionFiles,
   hasPointerBlock,
   ensurePointerInjected,
+  ensurePointerInjectedAll,
   stripPointer,
+  stripPointerAll,
   renderPointerBody,
 };

package/core/instructions/README.md

@@ -0,0 +1,69 @@
+# Instruction sources — the three-tier variation model (ADR-0011)
+
+The primary instruction file each agent auto-loads (`CLAUDE.md` for Claude Code,
+`AGENTS.md` for every AGENTS.md-standard agent) is **generated**, never
+hand-edited. It is a projection of **(principal constants × per-agent variation
+manifest)**. Regenerate with `npm run generate-instructions`; the suite's drift
+guard fails if a committed template diverges from its sources.
+
+## The three tiers
+
+| Tier | What | Where | Rule |
+|------|------|-------|------|
+| **1 — Principal constants** (the neutral spine) | Navigation table, Rules 1–15, Naming, Constraints, Project Extensions pointer | `core/instructions/navigation.md`, `core/instructions/rules-body.md` | **Byte-identical** across every agent + surface (`CLAUDE.md` ≡ `AGENTS.md` body) |
+| **2 — Variation manifest** | Everything that varies per agent | `adapters/<agent>/instructions/manifest.json` | One declarative record; generator auto-discovers it (OCP) |
+| **3 — Surface delta** | Irreducibly agent-specific integration prose + the task-tool mapping line | `adapters/<agent>/instructions/surfaces.md` (optional) | A scoped delta, never the file's whole identity (SRP) |
+
+The rules body carries **no agent-specific token** — the task tool is named only
+in the Tier-3 delta, which every agent still loads. That is what makes the spine
+byte-identical (and therefore a testable invariant, not a claim).
+
+## `manifest.json` schema
+
+```json
+{
+  "id": "opencode",
+  "displayName": "opencode",
+  "surface": "agents-md",
+  "taskTool": "the built-in **task** tool (subagent fan-out)",
+  "taskToolName": "The task tool",
+  "hasSurfaceDelta": true
+}
+```
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `id` | string | Adapter id — must match the `adapters/<id>/` directory name |
+| `displayName` | string | Human name used in the header scaffold + integration heading |
+| `surface` | `"claude-md"` \| `"agents-md"` | Which instruction file this agent reads; drives the install destination |
+| `taskTool` | string | Rendered into the Tier-3 task-tool mapping line (may contain markdown) |
+| `taskToolName` | string | Capitalized short form for prose references |
+| `hasSurfaceDelta` | boolean | Whether a `surfaces.md` integration delta exists for this agent |
+
+## Assembly order
+
+```
+header (scaffold, display name from manifest)
+  → navigation (Tier 1)
+  → surfaces delta (Tier 3, if hasSurfaceDelta)
+  → rules body (Tier 1, agent-neutral)
+  → Project Extensions pointer tail (ADR-0010)
+```
+
+## Adding a new agent (the OCP path)
+
+1. Create `adapters/<id>/instructions/manifest.json`.
+2. Optionally add `adapters/<id>/instructions/surfaces.md` (integration delta).
+3. Run `npm run generate-instructions`.
+
+No edit to `scripts/generate-instructions.js` is required — it discovers
+adapters by scanning `adapters/*/instructions/`. A suite test proves this by
+generating for a synthetic adapter with zero generator edits.
+
+## AGENTS.md when multiple AGENTS.md agents are installed
+
+`AGENTS.md` is a shared standard, so one repo can host several AGENTS.md agents.
+The committed per-agent template is the single-agent (N=1) projection. At
+install/upgrade, when `installed.json.agents` holds more than one `agents-md`
+agent, `AGENTS.md` is **composed**: the neutral spine once, plus one integration
+section per installed AGENTS.md agent. `CLAUDE.md` is unaffected (Claude-only).

package/core/instructions/rules-body.md

@@ -19,7 +19,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use {{TASK_TOOL}} to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -37,7 +37,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "{{TASK_TOOL_NAME}} is enough" — {{TASK_TOOL_NAME}} is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries

package/core/lib/instruction-compose.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// ADR-0011 — the instruction file is a projection of
+// (principal constants × per-agent variation manifest).
+//
+// Pure assembly logic, shipped in core/ so BOTH build-time generation
+// (scripts/generate-instructions.js) and install-time multi-agent AGENTS.md
+// composition (bin/momentum.js) use ONE code path. Every function takes
+// `root` = the momentum package/repo root that holds core/ + adapters/.
+//
+// Three tiers:
+//   1. Principal constants (neutral spine): core/instructions/navigation.md +
+//      rules-body.md — byte-identical across every agent + surface.
+//   2. Variation manifest: adapters/<id>/instructions/manifest.json.
+//   3. Surface delta: adapters/<id>/instructions/surfaces.md (optional).
+//
+// Assembly:
+//   marker → header → navigation → (per agent: surfaces? + task-tool note)
+//     → neutral rules body → Project Extensions pointer tail (ADR-0010)
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER_COMMENT = [
+  '<!-- momentum-managed (generated) — regenerate with `npm run generate-instructions`',
+  '     in the momentum repo; sources: core/instructions/ + adapters/<agent>/instructions/.',
+  "     Everything above '## Project Extensions' may be replaced by `momentum upgrade`. -->",
+].join('\n');
+
+// ADR-0010: `## Project Extensions` is a managed POINTER to specs/project-rules.md,
+// not an authoring surface. Kept byte-identical to core/lib/project-rules.js.
+const EXTENSIONS_TAIL = [
+  '---',
+  '',
+  '## Project Extensions',
+  '',
+  '<!-- momentum:project-rules-pointer -->',
+  '> **Project-specific rules live in `specs/project-rules.md`** — read it now.',
+  '> Session-start self-audits, project constraints, and any project-specific',
+  '> guidance are there, shared identically by every agent (ADR-0010). This',
+  '> section is a momentum-managed pointer; edit `specs/project-rules.md`, not',
+  '> this file.',
+].join('\n');
+
+function readFragment(root, rel) {
+  return fs.readFileSync(path.join(root, ...rel), 'utf8');
+}
+
+/** Discover every adapter that ships an instruction manifest (OCP: add a dir, no edits). */
+function discoverAgents(root) {
+  const dir = path.join(root, 'adapters');
+  return fs
+    .readdirSync(dir)
+    .filter((id) => fs.existsSync(path.join(dir, id, 'instructions', 'manifest.json')))
+    .sort();
+}
+
+function readManifest(root, id) {
+  const m = JSON.parse(readFragment(root, ['adapters', id, 'instructions', 'manifest.json']));
+  for (const key of ['id', 'displayName', 'surface', 'taskTool', 'taskToolName']) {
+    if (typeof m[key] !== 'string' || !m[key]) {
+      throw new Error(`adapters/${id}/instructions/manifest.json: missing/invalid "${key}"`);
+    }
+  }
+  if (m.id !== id) throw new Error(`manifest id "${m.id}" != adapter dir "${id}"`);
+  if (m.surface !== 'claude-md' && m.surface !== 'agents-md') {
+    throw new Error(`adapters/${id}: surface "${m.surface}" — expected claude-md | agents-md`);
+  }
+  return m;
+}
+
+/** The install destination filename implied by the surface. */
+function surfaceDestination(surface) {
+  if (surface === 'claude-md') return 'CLAUDE.md';
+  if (surface === 'agents-md') return 'AGENTS.md';
+  throw new Error(`unknown surface "${surface}"`);
+}
+
+/** Where this agent's committed (N=1) template lives, derived from its surface. */
+function templatePath(id, surface) {
+  if (surface === 'claude-md') return ['core', 'specs-templates', 'CLAUDE.md'];
+  if (surface === 'agents-md') return ['adapters', id, 'instructions', 'AGENTS.md'];
+  throw new Error(`unknown surface "${surface}" for adapter "${id}"`);
+}
+
+/** Header: single scaffold constant, agent display name(s) the only variable. */
+function renderHeader(manifests) {
+  const title = '# Project Rules: <Project Name>';
+  if (manifests.length === 1) {
+    return `${title}\n\n> ${manifests[0].displayName} configuration for this momentum-managed project.`;
+  }
+  const names = manifests.map((m) => m.displayName).join(', ');
+  return (
+    `${title}\n\n> Configuration for this momentum-managed project. This shared ` +
+    `AGENTS.md serves ${manifests.length} agents (${names}); each has its own ` +
+    `integration section below.`
+  );
+}
+
+/** The one agent-specific line lifted out of the neutral spine (SRP). */
+function renderTaskToolNote(m) {
+  return [
+    '## In-Session Task Tool',
+    '',
+    `When a rule mentions tracking in-session progress (Rule 2), ${m.displayName}'s ` +
+      `task tool is ${m.taskTool} — in-session only; the durable record is ` +
+      '`specs/phases/<phase>/tasks.md`.',
+  ].join('\n');
+}
+
+function readSurfaces(root, m) {
+  if (!m.hasSurfaceDelta) return null;
+  const p = path.join(root, 'adapters', m.id, 'instructions', 'surfaces.md');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+}
+
+function finalize(parts) {
+  const content = parts.map((p) => p.replace(/\s+$/, '')).join('\n\n') + '\n';
+  const leftover = content.match(/\{\{[A-Z_]+\}\}/);
+  if (leftover) throw new Error(`unrendered placeholder ${leftover[0]}`);
+  return content;
+}
+
+/**
+ * Compose an instruction file for one or more agents.
+ * - Single id → the committed N=1 projection (a static template).
+ * - Multiple ids → neutral spine + one integration section per agent
+ *   (install-time AGENTS.md when several AGENTS.md agents are installed).
+ */
+function composeInstruction(root, ids) {
+  if (!ids.length) throw new Error('composeInstruction: no agents');
+  const manifests = ids.map((id) => readManifest(root, id));
+  const navigation = readFragment(root, ['core', 'instructions', 'navigation.md']);
+  const body = readFragment(root, ['core', 'instructions', 'rules-body.md']);
+
+  const parts = [MARKER_COMMENT, renderHeader(manifests), navigation];
+  for (const m of manifests) {
+    const surfaces = readSurfaces(root, m);
+    if (surfaces) parts.push(surfaces);
+    parts.push(renderTaskToolNote(m));
+  }
+  parts.push(body, EXTENSIONS_TAIL);
+  return finalize(parts);
+}
+
+/** One committed template descriptor for a single agent. */
+function generateFor(root, id) {
+  const m = readManifest(root, id);
+  const target = templatePath(id, m.surface);
+  return {
+    agent: id,
+    targetRel: target.join('/'),
+    targetPath: path.join(root, ...target),
+    content: composeInstruction(root, [id]),
+    manifest: m,
+  };
+}
+
+function generateAll(root) {
+  return discoverAgents(root).map((id) => generateFor(root, id));
+}
+
+module.exports = {
+  MARKER_COMMENT,
+  EXTENSIONS_TAIL,
+  discoverAgents,
+  readManifest,
+  surfaceDestination,
+  templatePath,
+  renderHeader,
+  renderTaskToolNote,
+  composeInstruction,
+  generateFor,
+  generateAll,
+};

package/core/lib/okf-types.js

@@ -23,6 +23,7 @@ function isReserved(relPath) {
 const RULES = [
   [/^status\.md$/, 'Status'],
   [/^config\.md$/, 'Config'],
+  [/^project-rules\.md$/, 'Project Rules'],
   [/^backlog\/backlog\.md$/, 'Backlog'],
   [/^backlog\/details\/.+\.md$/, 'Backlog Detail'],
   [/^planning\/roadmap\.md$/, 'Roadmap'],

package/core/lib/project-rules.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * `specs/project-rules.md` — the single shared home for project-specific PROSE
+ * (Phase 28, ADR-0010). Every agent instruction file's `## Project Extensions`
+ * section becomes a managed POINTER to this file, so project rules live once and
+ * cannot diverge across adapters.
+ *
+ * This module owns:
+ *   - the pointer block that replaces `## Project Extensions`,
+ *   - the `project-rules.md` scaffold,
+ *   - `migrateProjectExtensions()` — the migrate-never-drop upgrade path that
+ *     moves an instruction file's authored extensions into project-rules.md and
+ *     rewrites its `## Project Extensions` as the pointer.
+ *
+ * Pure logic is exported separately from the fs-touching migration so it is
+ * unit-testable. Zero dependencies — node builtins only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = '## Project Extensions';
+const POINTER_SENTINEL = '<!-- momentum:project-rules-pointer -->';
+const PROJECT_RULES_REL = 'project-rules.md';
+
+/** The managed pointer block that IS the `## Project Extensions` section. */
+function renderPointerBlock() {
+  return [
+    MARKER,
+    '',
+    POINTER_SENTINEL,
+    '> **Project-specific rules live in `specs/project-rules.md`** — read it now.',
+    '> Session-start self-audits, project constraints, and any project-specific',
+    '> guidance are there, shared identically by every agent (ADR-0010). This',
+    '> section is a momentum-managed pointer; edit `specs/project-rules.md`, not',
+    '> this file.',
+    '',
+  ].join('\n');
+}
+
+/** Fresh `project-rules.md` scaffold (optionally carrying migrated body). */
+function renderProjectRules(projectName, migratedBody) {
+  const head = [
+    '---',
+    'type: Project Rules',
+    '---',
+    '',
+    `# Project Rules — ${projectName || 'this project'}`,
+    '',
+    '> Project-specific rules every agent reads — referenced by each instruction',
+    "> file's `## Project Extensions` pointer (ADR-0010). One home, shared by all",
+    '> adapters. Edit freely. For a rule that applies to only one agent, annotate',
+    '> it inline (e.g. *(Claude Code only)*).',
+    '',
+  ].join('\n');
+  const body = (migratedBody && migratedBody.trim())
+    ? migratedBody.trim() + '\n'
+    : '_(no project-specific rules yet)_\n';
+  return head + body;
+}
+
+/**
+ * Extract authored prose from a `## Project Extensions` region — everything
+ * after the heading and its leading `>` boilerplate note. Returns '' when the
+ * region is empty, boilerplate-only, or already the pointer.
+ */
+function extractAuthoredProse(extensionsRegion) {
+  if (!extensionsRegion) return '';
+  if (extensionsRegion.includes(POINTER_SENTINEL)) return ''; // already a pointer
+  const lines = extensionsRegion.replace(/^\n+/, '').split('\n');
+  // drop the `## Project Extensions` heading line
+  if (lines[0] && lines[0].trim() === MARKER) lines.shift();
+  // drop leading blank + blockquote boilerplate lines
+  while (lines.length && (lines[0].trim() === '' || lines[0].trimStart().startsWith('>'))) {
+    lines.shift();
+  }
+  return lines.join('\n').trim();
+}
+
+/** Replace a file's `## Project Extensions` region with the pointer block. */
+function pointerizeContent(content) {
+  const idx = content.indexOf('\n' + MARKER);
+  const managed = idx === -1 ? content.replace(/\s+$/, '') : content.slice(0, idx).replace(/\s+$/, '');
+  return managed + '\n\n' + renderPointerBlock();
+}
+
+/** True when a file's extensions region is already the managed pointer. */
+function isPointerized(content) {
+  return content.includes(POINTER_SENTINEL);
+}
+
+/**
+ * Migrate one instruction file's Project Extensions into project-rules.md and
+ * rewrite the section as the pointer. Migrate-never-drop, idempotent.
+ *
+ * @param {string} instructionFile absolute path (CLAUDE.md / AGENTS.md)
+ * @param {string} specsDir        absolute path to the project's specs/ dir
+ * @param {object} [opts] { dryRun, projectName }
+ * @returns {{ changed, appended, alreadyPointer, proseChars }}
+ */
+function migrateProjectExtensions(instructionFile, specsDir, opts = {}) {
+  const dryRun = Boolean(opts.dryRun);
+  const result = { changed: false, appended: false, alreadyPointer: false, proseChars: 0 };
+  if (!fs.existsSync(instructionFile)) return result;
+
+  const content = fs.readFileSync(instructionFile, 'utf8');
+  if (isPointerized(content)) { result.alreadyPointer = true; return result; }
+
+  const idx = content.indexOf('\n' + MARKER);
+  // No `## Project Extensions` marker → a pre-marker / custom file. Leave it to
+  // the standard upgrade's pre-marker path (backup .bak + append under marker),
+  // which preserves the user's content; never pointerize it here.
+  if (idx === -1) { result.noMarker = true; return result; }
+  const extensionsRegion = content.slice(idx);
+  const prose = extractAuthoredProse(extensionsRegion);
+  result.proseChars = prose.length;
+
+  const rulesPath = path.join(specsDir, PROJECT_RULES_REL);
+
+  if (prose) {
+    const label = path.basename(instructionFile);
+    const heading = `## Migrated from ${label}`;
+    let existing = fs.existsSync(rulesPath) ? fs.readFileSync(rulesPath, 'utf8') : null;
+    if (existing === null) {
+      existing = renderProjectRules(opts.projectName, '');
+    }
+    // Idempotent: only append if this file's migration block isn't already there.
+    if (!existing.includes(heading)) {
+      const block = `\n${heading}\n\n${prose}\n`;
+      const next = existing.replace(/\s+$/, '') + '\n' + block;
+      if (!dryRun) {
+        fs.mkdirSync(specsDir, { recursive: true });
+        fs.writeFileSync(rulesPath, next);
+      }
+      result.appended = true;
+    }
+  }
+
+  // Rewrite the instruction file's extensions region as the pointer.
+  const pointerized = pointerizeContent(content);
+  if (pointerized !== content) {
+    if (!dryRun) fs.writeFileSync(instructionFile, pointerized);
+    result.changed = true;
+  }
+
+  // The pointer must resolve: ensure project-rules.md exists (scaffold if the
+  // section had no prose to migrate), so we never leave a dangling pointer.
+  if (result.changed && !fs.existsSync(rulesPath) && !dryRun) {
+    fs.mkdirSync(specsDir, { recursive: true });
+    fs.writeFileSync(rulesPath, renderProjectRules(opts.projectName, ''));
+    result.scaffolded = true;
+  }
+  return result;
+}
+
+module.exports = {
+  MARKER,
+  POINTER_SENTINEL,
+  PROJECT_RULES_REL,
+  renderPointerBlock,
+  renderProjectRules,
+  extractAuthoredProse,
+  pointerizeContent,
+  isPointerized,
+  migrateProjectExtensions,
+};

package/core/specs-templates/CLAUDE.md

@@ -4,7 +4,7 @@
 
 # Project Rules: <Project Name>
 
-> Claude Code configuration for this project.
+> Claude Code configuration for this momentum-managed project.
 
 ## Navigation (Where to Find Things)
 
@@ -22,6 +22,10 @@
 
 ---
 
+## In-Session Task Tool
+
+When a rule mentions tracking in-session progress (Rule 2), Claude Code's task tool is the built-in **TodoWrite** tool — in-session only; the durable record is `specs/phases/<phase>/tasks.md`.
+
 ## Autonomous Behaviors (Always-On Rules)
 
 ### Rule 1: Always Orient First
@@ -43,7 +47,7 @@ After completing ANY meaningful work, automatically update:
 2. **`specs/status.md`** — if phase progress, blockers, or P0 items changed (touch only your own lane's row — Rule 15)
 3. **`specs/changelog/YYYY-MM.md`** — log what changed (one line per change, append-only)
 
-Use the built-in **TodoWrite** tool to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
+Use your in-session task-tracking tool (named in the "In-Session Task Tool" note above) to track in-session task progress. Do NOT wait for the user to ask you to update tracking.
 
 #### Why
 Tracking debt compounds invisibly. A task list one day stale is recoverable; one week stale is fiction. Status drift is how phases silently lose direction.
@@ -61,7 +65,7 @@ Tracking debt compounds invisibly. A task list one day stale is recoverable; one
 #### Anti-Rationalization Counters
 
 - "It's faster to do the work first and track at the end" — wrong: reconstruction takes 2-3× longer than real-time logging.
-- "TodoWrite is enough" — TodoWrite is in-session only; `tasks.md` is the durable record.
+- "Your in-session task-tracking tool is enough" — it is in-session only; `tasks.md` is the durable record.
 - "Mid-task tracking interrupts flow" — a one-line update costs <30s; reconstructing a day later costs 30 minutes.
 
 ### Rule 3: Auto-Track Discoveries
@@ -484,6 +488,9 @@ Use `infra:` for CI, build, deploy, tooling, and release-pipeline changes that d
 
 ## Project Extensions
 
-> Everything below this heading is preserved across `momentum upgrade`.
-> Add project-specific navigation, rules, cross-repo references, etc. here.
-> Anything above this heading is managed by momentum and may be replaced on upgrade.
+<!-- momentum:project-rules-pointer -->
+> **Project-specific rules live in `specs/project-rules.md`** — read it now.
+> Session-start self-audits, project constraints, and any project-specific
+> guidance are there, shared identically by every agent (ADR-0010). This
+> section is a momentum-managed pointer; edit `specs/project-rules.md`, not
+> this file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limina-labs/momentum",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {

package/adapters/antigravity/instructions/header.md

@@ -1,3 +0,0 @@
-# Project Rules: <Project Name>
-
-> Antigravity configuration for this momentum-managed project.

package/adapters/antigravity/instructions/vars.json

@@ -1 +0,0 @@
-{ "TASK_TOOL": "the native **task list** artifact (task.md)", "TASK_TOOL_NAME": "The task-list artifact" }

package/adapters/claude-code/instructions/header.md

@@ -1,3 +0,0 @@
-# Project Rules: <Project Name>
-
-> Claude Code configuration for this project.

package/adapters/claude-code/instructions/vars.json

@@ -1 +0,0 @@
-{ "TASK_TOOL": "the built-in **TodoWrite** tool", "TASK_TOOL_NAME": "TodoWrite" }

package/adapters/codex/instructions/header.md

@@ -1,3 +0,0 @@
-# Project Rules: <Project Name>
-
-> Codex configuration for this momentum-managed project.

package/adapters/codex/instructions/vars.json

@@ -1 +0,0 @@
-{ "TASK_TOOL": "the built-in **plan** tool", "TASK_TOOL_NAME": "The plan tool" }

package/adapters/opencode/instructions/header.md

@@ -1,3 +0,0 @@
-# Project Rules: <Project Name>
-
-> opencode configuration for this momentum-managed project.

package/adapters/opencode/instructions/vars.json

@@ -1 +0,0 @@
-{ "TASK_TOOL": "the built-in **task** tool (subagent fan-out)", "TASK_TOOL_NAME": "The task tool" }