@limina-labs/momentum 0.34.0 → 0.35.0

package/adapters/antigravity/instructions/AGENTS.md

@@ -638,6 +638,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/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 |
@@ -692,6 +692,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/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 |
@@ -605,6 +605,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/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}".`);

package/bin/momentum.js

@@ -1348,11 +1348,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
@@ -1983,12 +2004,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/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

@@ -484,6 +484,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.35.0",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {