start-vibing-stacks 2.25.0 → 2.26.0

package/stacks/_shared/commands/validate.md

@@ -1,28 +1,113 @@
 ---
 name: validate
-description: Run the full quality gate (typecheck → lint → test → build) using the stack's commands from active-project.json.
-version: 1.0.0
+description: Run the full quality gate (typecheck → lint → test → build) using THIS project's `active-project.json#qualityGates`. Per-stack reference is below.
+version: 1.1.0
 ---
 
 # /validate — Run Full Validation
 
-Read the quality gates from `.claude/config/active-project.json#qualityGates` and run them in order. Stop at the first failure.
+## How it works (canonical — always use this)
+
+1. **Read the gates from `.claude/config/active-project.json#qualityGates`.** This is the **only** source of truth — it was populated at install time from the active stack and reflects this project's actual tooling.
+2. Run each gate in `order` ascending; stop at the first failure that has `required: true`.
+3. If a gate has `appliesTo: ["nextjs", ...]`, only run it when `framework` in `active-project.json` matches.
 
 ```bash
-jq -r '.qualityGates' .claude/config/active-project.json
+jq -r '.qualityGates | sort_by(.order) | .[] | "\(.order). \(.name) (required=\(.required)): \(.command)"' .claude/config/active-project.json
+```
+
+`commit-manager` refuses to commit while `/validate` is failing.
+
+---
+
+## Per-stack reference (suggested — only used if `active-project.json` is missing or corrupted)
+
+This block exists so the model has a stack-aware fallback. **Do not pick from here when `active-project.json#qualityGates` is present and valid** — that JSON always wins.
+
+```json
+{
+  "python": {
+    "_default": {
+      "typecheck": "mypy .",
+      "lint":      "ruff check .",
+      "format":    "ruff format .",
+      "test":      "pytest --tb=short",
+      "serve":     "uvicorn app.main:app --reload"
+    },
+    "frameworks": {
+      "fastapi":  { "test": "pytest --tb=short" },
+      "django":   { "test": "python manage.py test", "migrate": "python manage.py migrate" },
+      "flask":    { "test": "pytest --tb=short" },
+      "scripts":  { "test": "pytest --tb=short" }
+    },
+    "_runOrder": ["typecheck", "lint", "test"]
+  },
+
+  "nodejs": {
+    "_default": {
+      "typecheck": "bun run typecheck",
+      "lint":      "bun run lint",
+      "format":    "bun run format",
+      "test":      "bun run test",
+      "build":     "bun run build",
+      "serve":     "bun run dev"
+    },
+    "frameworks": {
+      "nextjs": {
+        "_extra": [
+          { "name": "RouteSlugs",   "command": "node scripts/check-route-slugs.mjs",   "order": 4, "required": true,  "why": "next build does not catch dynamic-route slug mismatch" },
+          { "name": "BuildScripts", "command": "node scripts/check-build-scripts.mjs", "order": 5, "required": true,  "why": "Vercel/Docker strip devDeps; scripts.build calling tsx/ts-node/vitest crash exit 127" }
+        ]
+      },
+      "nuxt":     { "build": "bun run build" },
+      "astro":    { "build": "bun run build" },
+      "express":  { "test": "bun run test" },
+      "fastify":  { "test": "bun run test" },
+      "vanilla":  { "test": "bun run test" }
+    },
+    "_runOrder": ["typecheck", "lint", "test", "_extra", "build"]
+  },
+
+  "php": {
+    "_default": {
+      "static":    "vendor/bin/phpstan analyse --level=6",
+      "test":      "vendor/bin/phpunit",
+      "format":    "vendor/bin/php-cs-fixer fix",
+      "serve":     "php artisan serve"
+    },
+    "frameworks": {
+      "laravel-octane": {
+        "serve": "php artisan octane:start --watch",
+        "_extraIfFrontend": ["typecheck", "lint", "viteManifest"]
+      },
+      "laravel":        { "_extraIfFrontend": ["typecheck", "lint", "viteManifest"] }
+    },
+    "_frontendChecks": {
+      "typecheck":    "npx tsc --noEmit",
+      "lint":         "npx eslint resources/js/",
+      "viteManifest": "node scripts/check-vite-manifest.mjs"
+    },
+    "_runOrder": ["static", "test", "typecheck", "lint", "viteManifest"]
+  }
+}
 ```
 
-Execution order (each step blocks the next):
+### How to read this fallback
+
+- `_default` — commands that always apply within the stack.
+- `frameworks.<framework>` — overrides or extras gated by `framework` in `active-project.json`.
+- `_extra` — additional gates with explicit `order` (PHP/Next.js use this for stack-specific static checks like vite-manifest, route-slugs, build-scripts).
+- `_runOrder` — order to chain when no `qualityGates` is available.
 
-| # | Gate | Typical commands |
-|---|---|---|
-| 1 | **Typecheck** | `npx tsc --noEmit` · `mypy .` · `vendor/bin/phpstan analyse` |
-| 2 | **Lint** | `npx eslint .` · `ruff check .` · `vendor/bin/pint --test` |
-| 3 | **Unit tests** | `npx vitest run` · `pytest` · `vendor/bin/phpunit` |
-| 4 | **E2E** (only if configured) | `npx playwright test` |
-| 5 | **Build** | `npm run build` · `composer dump-autoload --optimize` |
+If `.claude/config/active-project.json#qualityGates` is missing, **do not silently fall back** — instead:
+
+1. Print a warning: `WARN: active-project.json#qualityGates missing — using fallback for stack=<X>, framework=<Y>`.
+2. Run the fallback in `_runOrder`.
+3. Recommend the user re-run `npx start-vibing-stacks` (or `migrate --apply`) to repair the config.
+
+---
 
-Output format (one line per gate):
+## Output format
 
 ```
 typecheck: PASS  (1.4s)
@@ -34,4 +119,4 @@ build:     PASS  (3.1s)
 ✅ All gates passed — safe to invoke commit-manager
 ```
 
-If any gate fails, print the failure output and exit non-zero. `commit-manager` will refuse to commit while validation is failing.
+If any required gate fails, print its full output and exit non-zero. Optional gates (`required: false`) print a warning but do not block.

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);