start-vibing-stacks 2.25.2 → 2.26.0

package/stacks/_shared/hooks/scope.ts

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+// @sv-version: 1.0.0
+/**
+ * `scope` — Per-Instance Commit Scoping CLI
+ *
+ * Solves: in multi-instance Claude sessions, `git add .` / `git add -A` pulls
+ * in changes from peer sessions, producing tangled commits where instance N
+ * unintentionally ships instance M's uncommitted work.
+ *
+ * Source of truth for "what did THIS session edit?":
+ *   `.claude/state/sessions/<id>.json#filesTouched`
+ * which is maintained by `post-tool-use.ts` (capped at 50, dedup-keep-last).
+ *
+ * Usage:
+ *   scope status                        Show this session's files vs peers' files vs untracked.
+ *   scope stage [--include-conflicted]  `git reset`, then `git add` only this session's dirty files.
+ *                                       Refuses files a peer touched in the last 5 min unless
+ *                                       --include-conflicted.
+ *   scope diff                          `git diff` for files this session touched.
+ *   scope commit "<msg>" [--push]       stage + commit + optional push.
+ *
+ * Session discovery: --session <id>, else $CLAUDE_SESSION_ID, else single active session.
+ *
+ * Exit codes:
+ *   0  ok
+ *   1  argument / state error
+ *   2  refused (collision detected; pass --include-conflicted to override)
+ *
+ * Run: npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" <command>
+ */
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import {
+  ACTIVE_MS,
+  COLLISION_WINDOW_MS,
+  ageMs,
+  getProjectDir,
+  getStateDir,
+  listSessionFiles,
+  readJsonSafe,
+  readSession,
+  shortId,
+  tailFileTouches,
+  type FileTouch,
+  type SessionRecord,
+} from './_state.js';
+
+interface GitStatus {
+  modified: Set<string>;
+  staged: Set<string>;
+  untracked: Set<string>;
+}
+
+interface ScopeReport {
+  mine: string[];
+  conflicted: { file: string; peer: SessionRecord | null; ageSec: number }[];
+  otherDirty: string[];
+}
+
+function parseFlag(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function loadAllSessions(stateDir: string): SessionRecord[] {
+  const out: SessionRecord[] = [];
+  for (const file of listSessionFiles(stateDir)) {
+    const rec = readJsonSafe<SessionRecord>(file);
+    if (rec) out.push(rec);
+  }
+  return out;
+}
+
+function resolveSessionId(stateDir: string, explicit?: string): string | null {
+  if (explicit) return explicit;
+  const fromEnv = process.env['CLAUDE_SESSION_ID'];
+  if (fromEnv) return fromEnv;
+  const active = loadAllSessions(stateDir).filter(s => ageMs(s.lastSeenAt) < ACTIVE_MS);
+  if (active.length === 1) return active[0]!.sessionId;
+  return null;
+}
+
+function git(args: string[], cwd: string): { code: number; stdout: string; stderr: string } {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return { code: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+function gitDirty(projectDir: string): GitStatus {
+  const r = git(['status', '--porcelain=v1', '-z'], projectDir);
+  const out: GitStatus = {
+    modified: new Set<string>(),
+    staged: new Set<string>(),
+    untracked: new Set<string>(),
+  };
+  if (r.code !== 0) return out;
+  // -z = NUL-terminated. Format: `XY<space>path\0` (renames add a second `\0orig`)
+  // We deliberately treat the rename path as the new name only; orig is consumed.
+  const parts = r.stdout.split('\0').filter(Boolean);
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i]!;
+    if (entry.length < 4) continue;
+    const xy = entry.slice(0, 2);
+    const path = entry.slice(3);
+    const X = xy[0]!;
+    const Y = xy[1]!;
+    if (X === 'R' || Y === 'R') {
+      // Next NUL-token is the original path; skip it for our purposes.
+      i++;
+    }
+    if (X !== ' ' && X !== '?') out.staged.add(path);
+    if (Y !== ' ' && Y !== '?') out.modified.add(path);
+    if (X === '?' && Y === '?') out.untracked.add(path);
+  }
+  return out;
+}
+
+function classify(stateDir: string, sessionId: string, projectDir: string): ScopeReport {
+  const session = readSession(stateDir, sessionId);
+  const tracked = new Set(session?.filesTouched || []);
+  const status = gitDirty(projectDir);
+  const dirty = new Set<string>([...status.modified, ...status.untracked]);
+
+  const touches = tailFileTouches(stateDir);
+  const peerById = new Map(loadAllSessions(stateDir).map(p => [p.sessionId, p]));
+  const peerTouches = new Map<string, FileTouch>();
+  for (const t of touches) {
+    if (t.sessionId === sessionId) continue;
+    if (ageMs(t.ts) > COLLISION_WINDOW_MS) continue;
+    const prev = peerTouches.get(t.file);
+    if (!prev || Date.parse(t.ts) > Date.parse(prev.ts)) peerTouches.set(t.file, t);
+  }
+
+  const mine: string[] = [];
+  const conflicted: ScopeReport['conflicted'] = [];
+  for (const file of tracked) {
+    if (!dirty.has(file)) continue;
+    const conflict = peerTouches.get(file);
+    if (conflict) {
+      conflicted.push({
+        file,
+        peer: peerById.get(conflict.sessionId) || null,
+        ageSec: Math.round(ageMs(conflict.ts) / 1000),
+      });
+    } else {
+      mine.push(file);
+    }
+  }
+
+  const otherDirty: string[] = [];
+  for (const f of dirty) {
+    if (!tracked.has(f)) otherDirty.push(f);
+  }
+
+  return { mine, conflicted, otherDirty };
+}
+
+function cmdStatus(stateDir: string, projectDir: string, args: string[]): number {
+  const sessionId = resolveSessionId(stateDir, parseFlag(args, '--session'));
+  if (!sessionId) {
+    console.error('Cannot resolve session ID. Set CLAUDE_SESSION_ID or pass --session <id>.');
+    console.error('Tip: run `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list`.');
+    return 1;
+  }
+  const session = readSession(stateDir, sessionId);
+  if (!session) {
+    console.error(`Session ${shortId(sessionId)} not registered. Has the SessionStart hook run?`);
+    return 1;
+  }
+
+  const { mine, conflicted, otherDirty } = classify(stateDir, sessionId, projectDir);
+  const status = gitDirty(projectDir);
+
+  console.log(
+    `Session ${shortId(sessionId)} "${session.title}" (branch ${session.gitBranch || '?'})`
+  );
+  console.log(`Files in session.filesTouched: ${session.filesTouched.length} (cap 50, dedup)`);
+  console.log();
+  console.log(`SAFE TO STAGE (${mine.length}):`);
+  if (mine.length === 0) {
+    console.log('  (none)');
+  } else {
+    for (const f of mine) console.log(`  + ${f}`);
+  }
+
+  if (conflicted.length > 0) {
+    console.log();
+    console.log(`CONFLICTED — peer also touched in last 5 min (${conflicted.length}):`);
+    for (const c of conflicted) {
+      const who = c.peer
+        ? `${shortId(c.peer.sessionId)} "${c.peer.title}"`
+        : '(unknown peer)';
+      console.log(`  ! ${c.file}  ←  ${who}, ${c.ageSec}s ago`);
+    }
+    console.log('  Coordinate via `/peers notify <id> "..."`, OR re-run with --include-conflicted.');
+  }
+
+  if (otherDirty.length > 0) {
+    console.log();
+    console.log(`NOT YOURS — dirty but not in filesTouched (${otherDirty.length}):`);
+    for (const f of otherDirty) console.log(`  · ${f}`);
+    console.log('  `scope stage` will LEAVE these alone (this is the whole point).');
+  }
+
+  if (status.staged.size > 0) {
+    console.log();
+    console.log(`CURRENTLY STAGED (${status.staged.size}):`);
+    for (const f of status.staged) console.log(`  ✓ ${f}`);
+    console.log('  `scope stage` runs `git reset` first — this state will be replaced.');
+  }
+
+  return 0;
+}
+
+function cmdStage(stateDir: string, projectDir: string, args: string[]): number {
+  const sessionId = resolveSessionId(stateDir, parseFlag(args, '--session'));
+  if (!sessionId) {
+    console.error('Cannot resolve session ID. Set CLAUDE_SESSION_ID or pass --session <id>.');
+    return 1;
+  }
+  const session = readSession(stateDir, sessionId);
+  if (!session) {
+    console.error(`Session ${shortId(sessionId)} not registered.`);
+    return 1;
+  }
+
+  const { mine, conflicted } = classify(stateDir, sessionId, projectDir);
+  const includeConflicted = hasFlag(args, '--include-conflicted');
+  const conflictedFiles = conflicted.map(c => c.file);
+  const toStage = includeConflicted ? [...mine, ...conflictedFiles] : mine;
+
+  if (toStage.length === 0) {
+    if (conflicted.length > 0) {
+      console.error(
+        `No safe files to stage. ${conflicted.length} conflicted file(s) — pass --include-conflicted to override.`
+      );
+      for (const c of conflicted) {
+        const who = c.peer
+          ? `${shortId(c.peer.sessionId)} "${c.peer.title}"`
+          : '(unknown)';
+        console.error(`  ! ${c.file}  ←  ${who}, ${c.ageSec}s ago`);
+      }
+      return 2;
+    }
+    console.error(
+      'No files to stage (this session has no dirty files in filesTouched).'
+    );
+    return 1;
+  }
+
+  // The `git reset` here is intentional: scope semantics own the index.
+  // Anything a peer staged previously will be unstaged; they will re-stage
+  // their own files via `scope stage` when they commit.
+  const resetR = git(['reset'], projectDir);
+  if (resetR.code !== 0) {
+    console.error(`git reset failed: ${resetR.stderr.trim()}`);
+    return 1;
+  }
+  const addR = git(['add', '--', ...toStage], projectDir);
+  if (addR.code !== 0) {
+    console.error(`git add failed: ${addR.stderr.trim()}`);
+    return 1;
+  }
+
+  console.log(`Staged ${toStage.length} file(s) from session ${shortId(sessionId)}:`);
+  for (const f of toStage) console.log(`  + ${f}`);
+
+  if (conflicted.length > 0 && !includeConflicted) {
+    console.log();
+    console.log(`Skipped ${conflicted.length} conflicted file(s):`);
+    for (const c of conflicted) {
+      const who = c.peer
+        ? `${shortId(c.peer.sessionId)} "${c.peer.title}"`
+        : '(unknown)';
+      console.log(`  ! ${c.file}  ←  ${who}, ${c.ageSec}s ago`);
+    }
+    console.log('  Pass --include-conflicted to stage them anyway.');
+    console.log('  Review with: git diff --cached --stat');
+    return 2;
+  }
+
+  console.log();
+  console.log('Review with: git diff --cached --stat');
+  return 0;
+}
+
+function cmdDiff(stateDir: string, projectDir: string, args: string[]): number {
+  const sessionId = resolveSessionId(stateDir, parseFlag(args, '--session'));
+  if (!sessionId) {
+    console.error('Cannot resolve session ID. Set CLAUDE_SESSION_ID or pass --session <id>.');
+    return 1;
+  }
+  const session = readSession(stateDir, sessionId);
+  if (!session) {
+    console.error(`Session ${shortId(sessionId)} not registered.`);
+    return 1;
+  }
+
+  const files = session.filesTouched.filter(f => existsSync(join(projectDir, f)));
+  if (files.length === 0) {
+    console.error('This session has no tracked files (or none exist on disk).');
+    return 1;
+  }
+  const r = spawnSync('git', ['diff', '--', ...files], {
+    cwd: projectDir,
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}
+
+// Flags that take a value (the next token is consumed as the value, not as a positional).
+const VALUE_FLAGS = new Set(['--session']);
+
+function firstPositional(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith('--')) continue;
+    const prev = i > 0 ? args[i - 1]! : '';
+    if (VALUE_FLAGS.has(prev)) continue;
+    return a;
+  }
+  return undefined;
+}
+
+function cmdCommit(stateDir: string, projectDir: string, args: string[]): number {
+  const message = firstPositional(args);
+  if (!message) {
+    console.error('Usage: scope commit "<message>" [--push] [--include-conflicted] [--session <id>]');
+    return 1;
+  }
+
+  const stageCode = cmdStage(stateDir, projectDir, args);
+  if (stageCode === 1) return 1;
+  if (stageCode === 2 && !hasFlag(args, '--include-conflicted')) {
+    console.error();
+    console.error(
+      'Refusing to commit while conflicted files were skipped. ' +
+        'Resolve, OR re-run with --include-conflicted.'
+    );
+    return 2;
+  }
+
+  const commitR = git(['commit', '-m', message], projectDir);
+  process.stdout.write(commitR.stdout);
+  process.stderr.write(commitR.stderr);
+  if (commitR.code !== 0) return 1;
+
+  if (hasFlag(args, '--push')) {
+    const pushR = spawnSync('git', ['push'], { cwd: projectDir, stdio: 'inherit' });
+    return pushR.status ?? 1;
+  }
+  return 0;
+}
+
+function usage(): void {
+  console.log(`scope — per-instance commit scoping CLI
+
+Commands:
+  scope status   [--session <id>]
+  scope stage    [--session <id>] [--include-conflicted]
+  scope diff     [--session <id>]
+  scope commit   "<message>" [--session <id>] [--include-conflicted] [--push]
+
+Stages and commits ONLY the files this Claude session edited (per
+\`.claude/state/sessions/<id>.json#filesTouched\`). Refuses to stage
+files a peer session touched in the last 5 min unless --include-conflicted.
+
+Exit codes: 0=ok, 1=arg/state error, 2=conflict refusal.
+`);
+}
+
+function main(): void {
+  const [, , cmd, ...rest] = process.argv;
+  const projectDir = getProjectDir();
+  const stateDir = getStateDir(projectDir);
+
+  switch (cmd) {
+    case 'status':
+      process.exit(cmdStatus(stateDir, projectDir, rest));
+      break;
+    case 'stage':
+      process.exit(cmdStage(stateDir, projectDir, rest));
+      break;
+    case 'diff':
+      process.exit(cmdDiff(stateDir, projectDir, rest));
+      break;
+    case 'commit':
+      process.exit(cmdCommit(stateDir, projectDir, rest));
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      usage();
+      process.exit(0);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      usage();
+      process.exit(1);
+  }
+}
+
+main();

package/stacks/_shared/hooks/stop-validator.ts

@@ -1,16 +1,22 @@
 #!/usr/bin/env node
-// @sv-version: 1.1.0
+// @sv-version: 1.2.0
 /**
  * Stop Validator Hook — Start Vibing Stacks (Universal)
  *
  * Reads active-project.json to determine stack-specific validations.
  * Blocks task completion if:
  * 1. Branch != main (work must be merged)
- * 2. Git tree not clean
+ * 2. Git tree not clean — SCOPED TO THIS SESSION'S filesTouched when available
+ *    (multi-instance safe: peer N's dirty files do not block instance M's Stop)
  * 3. CLAUDE.md not updated
- * 4. CLAUDE.md missing required sections
+ * 4. CLAUDE.md missing required sections — accepts `## Last Change` OR `## Recent Changes`
  * 5. CLAUDE.md exceeds 40k chars
  * 6. Secret pattern detected in committed/staged files (uses gitleaks if present, fallback to regex)
+ *
+ * v1.2.0: per-instance scoping for the dirty-tree check + accept `## Recent Changes`
+ * (append-only LIFO) as a valid changelog section. Source of truth for "what did
+ * THIS session edit?" is `.claude/state/sessions/<id>.json#filesTouched`, maintained
+ * by `post-tool-use.ts`.
  */
 
 import { execSync } from 'child_process';
@@ -25,6 +31,7 @@ import {
   formatPeer,
   getStateDir,
   listPeerSessions,
+  readSession,
 } from './_state.js';
 
 const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
@@ -77,6 +84,31 @@ function getModifiedFiles(): string[] {
   return [...new Set([...staged, ...unstaged, ...untracked])];
 }
 
+/**
+ * Per-instance scoping: if a session id is provided AND state has filesTouched,
+ * return only the dirty files THIS session edited. Otherwise return the full
+ * dirty list (backward compatible). Falls back gracefully on any error.
+ */
+function getScopedDirtyFiles(sessionId: string | undefined): {
+  scoped: string[];
+  perInstance: boolean;
+  totalDirty: number;
+} {
+  const allDirty = getModifiedFiles();
+  if (!sessionId) return { scoped: allDirty, perInstance: false, totalDirty: allDirty.length };
+  try {
+    const stateDir = getStateDir(PROJECT_DIR);
+    const sess = readSession(stateDir, sessionId);
+    if (!sess || !Array.isArray(sess.filesTouched)) {
+      return { scoped: allDirty, perInstance: false, totalDirty: allDirty.length };
+    }
+    const set = new Set(sess.filesTouched);
+    return { scoped: allDirty.filter(f => set.has(f)), perInstance: true, totalDirty: allDirty.length };
+  } catch {
+    return { scoped: allDirty, perInstance: false, totalDirty: allDirty.length };
+  }
+}
+
 /**
  * Run a command capturing stdout, stderr and exit code without throwing.
  */
@@ -142,18 +174,27 @@ function scanSecrets(): string[] {
   return findings;
 }
 
-function validate(): HookResult {
+function validate(sessionId: string | undefined): HookResult {
   const branch = getBranch();
   const isMain = branch === 'main' || branch === 'master';
-  const modified = getModifiedFiles();
+  const { scoped: modified, perInstance, totalDirty } = getScopedDirtyFiles(sessionId);
   const isClean = modified.length === 0;
+  const scopeNote = perInstance
+    ? ` (this-session-scoped: ${modified.length}/${totalDirty} dirty; peer files ignored)`
+    : '';
+
+  // 1. Must be on main with clean tree (scoped to THIS session when possible).
+  //    Recommendation uses `/commit-mine` rather than `git add -A`, which would
+  //    pull in peer-session changes (see CLAUDE.md NRY "Instance N's commit bundling...").
+  const commitGuide = perInstance
+    ? `\n\nRecommended workflow (multi-instance safe):\n1. npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" status\n2. npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" stage\n3. git commit -m "type: description"\n4. git checkout main && git merge ${branch} && git push origin main && git branch -d ${branch}`
+    : `\n\nComplete git workflow:\n1. git add -A\n2. git commit -m "type: description"\n3. git checkout main\n4. git merge ${branch}\n5. git push origin main\n6. git branch -d ${branch}`;
 
-  // 1. Must be on main with clean tree
   if (!isMain && modified.length > 0) {
     return {
       continue: true,
       decision: 'block',
-      reason: `BLOCKED: On branch '${branch}' with ${modified.length} modified files.\n\nComplete git workflow:\n1. git add -A\n2. git commit -m "type: description"\n3. git checkout main\n4. git merge ${branch}\n5. git push origin main\n6. git branch -d ${branch}`,
+      reason: `BLOCKED: On branch '${branch}' with ${modified.length} modified files${scopeNote}.${commitGuide}`,
     };
   }
 
@@ -166,10 +207,13 @@ function validate(): HookResult {
   }
 
   if (!isClean) {
+    const stageHint = perInstance
+      ? `\n\nThese files were edited by THIS session. Commit only your scope:\n  npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>"`
+      : `\n\nCommit or stash before completing.`;
     return {
       continue: true,
       decision: 'block',
-      reason: `BLOCKED: ${modified.length} uncommitted files:\n${modified.slice(0, 10).map(f => `  - ${f}`).join('\n')}\n\nCommit or stash before completing.`,
+      reason: `BLOCKED: ${modified.length} uncommitted files${scopeNote}:\n${modified.slice(0, 10).map(f => `  - ${f}`).join('\n')}${stageHint}`,
     };
   }
 
@@ -193,10 +237,11 @@ function validate(): HookResult {
     };
   }
 
-  // 4. Required sections
+  // 4. Required sections — `## Last Change` (single, overwritten) OR `## Recent Changes`
+  //    (append-only LIFO, multi-instance safe) both satisfy the changelog slot.
   const required = [
     { pattern: /^# .+/m, name: 'Project Title (H1)' },
-    { pattern: /^## Last Change/m, name: 'Last Change' },
+    { pattern: /^## (Last Change|Recent Changes)/m, name: 'Last Change OR Recent Changes' },
     { pattern: /^## Stack/m, name: 'Stack' },
   ];
 
@@ -247,10 +292,10 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
-  const result = validate();
-
   // Multi-instance coordination side effects.
   const sessionId: string | undefined = hookInput.session_id || hookInput.sessionId;
+
+  const result = validate(sessionId);
   const eventName: string = hookInput.hook_event_name || hookInput.hookEventName || '';
   const isSessionEnd = /SessionEnd/i.test(eventName);
 

package/stacks/_shared/hooks/user-prompt-submit.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// @sv-version: 1.1.0
+// @sv-version: 1.2.0
 /**
  * UserPromptSubmit Hook — Start Vibing Stacks
  *
@@ -9,6 +9,10 @@
  *     from the first prompt (matches `claude --resume`), drain the inbox so
  *     peer messages reach the user before this turn runs, and warn if active
  *     peers exist.
+ *
+ * v1.2.0: workflow guidance now points at `## Recent Changes` (append-only LIFO)
+ * instead of `## Last Change` (overwritten). Aligned with `commit-manager` v3.0.0
+ * and `domain-updater` v3.0.0 — multi-instance safe.
  */
 
 import { existsSync, readFileSync } from 'fs';
@@ -159,11 +163,15 @@ async function main(): Promise<void> {
 
 3. Run quality gates: ${qualityCmd}
 
-4. COMMIT using conventional commits via commit-manager agent.
+4. COMMIT using conventional commits via commit-manager agent (v3.0.0+: stages only THIS session's files via scope.ts when .claude/state/ exists — peers' uncommitted files are never bundled).
 
 5. UPDATE CLAUDE.md:
-   a. "## Last Change" (date: ${today}, branch, summary)
-   b. Update ALL affected rule/flow sections
+   a. PREPEND a new entry under "## Recent Changes" — heading exactly:
+      "### ${today} · <branch> · <version-or-tag>" followed by 1-4 plain-text lines.
+      Append-only LIFO; cap 10 (drop ONLY the oldest if exceeded). Multi-instance safe.
+      Triggered automatically by domain-updater v3.0.0; do it manually only if running outside the chain.
+   b. Update ALL affected rule/flow sections (Critical Rules, FORBIDDEN, NRY) when the change
+      modifies how the project works.
 
 6. Run stop-validator before finishing.${standardsContext}${peersBlock}`;
 

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -123,7 +123,7 @@ End state in **both flows**: clean tree, on `main`, in sync with `origin/main`.
 - [ ] Quality gate passed (typecheck / lint / tests / build)
 - [ ] Security gate passed (`security-auditor` clean)
 - [ ] No secrets in diff (gitleaks)
-- [ ] CLAUDE.md `Last Change` updated when scope warrants it
+- [ ] CLAUDE.md `## Recent Changes` updated (PREPEND a new `### YYYY-MM-DD · branch · vX.Y.Z` block — append-only LIFO, cap 10; `domain-updater` v3.0.0+ does this automatically post-commit)
 - [ ] Conventional commit message drafted
 - [ ] Push target confirmed (`origin main` vs `origin feature/*`)
 

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -221,7 +221,11 @@ const issues: string[] = [];
 
 if (dirty)                                                    issues.push(`GIT_TREE_NOT_CLEAN: ${dirty.split('\n').length} file(s)`);
 if (existsSync('CLAUDE.md') &&
-    !readFileSync('CLAUDE.md', 'utf8').includes('Last Change')) issues.push('CLAUDE_MD_NOT_UPDATED');
+    !/^## (Last Change|Recent Changes)/m.test(readFileSync('CLAUDE.md', 'utf8'))) {
+  // Accepts the legacy `## Last Change` (single, overwritten) OR `## Recent Changes`
+  // (append-only LIFO, multi-instance safe — see claude-md-compactor §6.1).
+  issues.push('CLAUDE_MD_NOT_UPDATED');
+}
 
 const result = issues.length === 0
   ? { continue: false, decision: 'approve', reason: 'All checks passed' }

package/templates/CLAUDE-default.md

@@ -1,10 +1,14 @@
 # {{PROJECT_NAME}}
 
-## Last Change
+## Recent Changes
 
-**Branch:** main
-**Date:** {{DATE}}
-**Summary:** Initial project setup with start-vibing-stacks
+<!-- APPEND-ONLY LIFO. Each Claude instance PREPENDS a new `### YYYY-MM-DD · branch · vX.Y.Z` heading
+     + 1-4 lines below it. Drop only the OLDEST entry when count > 10. NEVER edit a peer's entry.
+     `domain-updater` v3.0.0+ does this automatically post-commit.
+     Compactor (`claude-md-compactor.md §5-§6`) enforces the cap, not the prepend. -->
+
+### {{DATE}} · main · v0.1.0
+Initial project setup with start-vibing-stacks.
 
 ## 30 Seconds Overview
 

package/templates/CLAUDE-nodejs.md

@@ -2,11 +2,15 @@
 
 > **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
 
-## Last Change
+## Recent Changes
 
-**Branch:** main
-**Date:** {{DATE}}
-**Summary:** Initial project setup with start-vibing-stacks (Node.js)
+<!-- APPEND-ONLY LIFO. Each Claude instance PREPENDS a new `### YYYY-MM-DD · branch · vX.Y.Z` heading
+     + 1-4 lines below it. Drop only the OLDEST entry when count > 10. NEVER edit a peer's entry.
+     `domain-updater` v3.0.0+ does this automatically post-commit.
+     Compactor (`claude-md-compactor.md §5-§6`) enforces the cap, not the prepend. -->
+
+### {{DATE}} · main · v0.1.0
+Initial project setup with start-vibing-stacks (Node.js).
 
 ## 30 Seconds Overview
 
@@ -90,7 +94,7 @@ project/
 
 | Change Type | Sections to Update |
 |-------------|-------------------|
-| Any file change | Last Change (branch, date, summary) |
+| Any file change | PREPEND new entry to `## Recent Changes` (heading: `### YYYY-MM-DD · branch · vX.Y.Z` + 1-4 lines) |
 | API/routes | Critical Rules, Architecture |
 | UI components | Architecture, Component Organization |
 | New feature | 30s Overview, Architecture |
@@ -98,10 +102,10 @@ project/
 | New dependency | Stack |
 | Workflow change | Workflow section |
 
-1. **Last Change** documents WHAT was done
-2. **Other sections** document HOW things work NOW
-3. **Both must be current** — updating only Last Change is insufficient
-4. Keep only the LATEST Last Change entry (no stacking)
+1. **`## Recent Changes`** documents WHAT was done across recent sessions (append-only LIFO, cap 10).
+2. **Other sections** document HOW things work NOW.
+3. **Both must be current** — prepending to Recent Changes is insufficient if rule sections went stale.
+4. **APPEND-ONLY** — PREPEND your entry below the HTML comment anchor; drop only the OLDEST entry when count > 10. NEVER edit a peer's entry, NEVER collapse two entries into one. Multi-instance safe by construction.
 
 ## Agent System
 
@@ -247,7 +251,7 @@ source: 'listed' as const;  // CORRECT (literal type)
 | Skip todo list creation | Loses track of tasks |
 | Skip documenter agent | Documentation is mandatory |
 | Skip domain documentation | MUST update domains/*.md |
-| Stack Last Change entries | Keep only the LATEST |
+| Overwrite `## Recent Changes` or collapse entries | PREPEND only; drop oldest when > 10 (NEVER edit peer entries) |
 | Use MUI/Chakra | Use shadcn/ui + Radix |
 | Skip CLAUDE.md update | MUST update after implementations |