start-vibing-stacks 2.25.2 → 2.28.0

package/README.md

@@ -173,7 +173,7 @@ Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
 6. QUALITY        quality-gate: typecheck → lint → test → build
 7. COMMIT         commit-manager — verifies gates, diff-driven message, push
 8. DOCUMENT       documenter — maps files/commits to domains, regenerates _index.json
-9. WISDOM         domain-updater — records session learnings, refreshes CLAUDE.md Last Change
+9. WISDOM         domain-updater — records session learnings, PREPENDS new entry to CLAUDE.md ## Recent Changes (append-only LIFO, cap 10, multi-instance safe)
 10. COMPACT       claude-md-compactor — triggers if CLAUDE.md > 20 KB
 ```
 
@@ -195,7 +195,7 @@ Steps 5–6 cannot be skipped — `security-auditor` and `quality-gate` veto `co
 | Edit policy | `Edit` known anchors; never `Write` over an existing domain | Diff stability for code review |
 | `summary_sha` | sha256 of the TL;DR block | Drift detector for CI hooks |
 
-This layer is **separate** from `CLAUDE.md`: that file holds project-wide rules and "Last Change"; the memory layer holds domain knowledge.
+This layer is **separate** from `CLAUDE.md`: that file holds project-wide rules and `## Recent Changes` (append-only LIFO, cap 10 entries, multi-instance safe — see `claude-md-compactor.md §6.1`); the memory layer holds domain knowledge.
 
 ---
 

package/dist/migrate.d.ts

@@ -10,7 +10,9 @@
  *  - commands: same `version:` frontmatter contract as skills/agents.
  *  - .claude/settings.json — patched idempotently to ensure the bundled hook
  *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
- *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    SessionEnd) is wired, plus high-reasoning defaults `effortLevel: "xhigh"`
+ *    and `permissions.defaultMode: "plan"` (only when MISSING — user choices are
+ *    never clobbered). Existing entries are preserved; only missing entries
  *    are appended. Atomic write (.tmp + rename).
  *  - .claude/state/ — runtime layout for multi-instance coordination is
  *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.

package/dist/migrate.js

@@ -10,7 +10,9 @@
  *  - commands: same `version:` frontmatter contract as skills/agents.
  *  - .claude/settings.json — patched idempotently to ensure the bundled hook
  *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
- *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    SessionEnd) is wired, plus high-reasoning defaults `effortLevel: "xhigh"`
+ *    and `permissions.defaultMode: "plan"` (only when MISSING — user choices are
+ *    never clobbered). Existing entries are preserved; only missing entries
  *    are appended. Atomic write (.tmp + rename).
  *  - .claude/state/ — runtime layout for multi-instance coordination is
  *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.
@@ -302,6 +304,26 @@ export function patchSettings(projectDir, dryRun) {
         }
         report.added.push(event);
     }
+    // High-reasoning defaults (v2.28.0). Only set when MISSING so we never clobber
+    // a user's explicit choice. `ultracode` is intentionally never written here:
+    // it is session-only (/effort) and cannot be persisted in settings.json.
+    if (settings.effortLevel === undefined) {
+        if (!dryRun)
+            settings.effortLevel = 'xhigh';
+        report.added.push('effortLevel:xhigh');
+    }
+    else {
+        report.alreadyPresent.push('effortLevel');
+    }
+    settings.permissions = settings.permissions || {};
+    if (settings.permissions.defaultMode === undefined) {
+        if (!dryRun)
+            settings.permissions.defaultMode = 'plan';
+        report.added.push('permissions.defaultMode:plan');
+    }
+    else {
+        report.alreadyPresent.push('permissions.defaultMode');
+    }
     if (!dryRun && report.added.length > 0 && !report.error) {
         mkdirSync(dirname(path), { recursive: true });
         writeFileAtomic(path, JSON.stringify(settings, null, '\t'));

package/dist/setup.js

@@ -226,6 +226,10 @@ export async function setupProject(projectDir, config, options = {}) {
             model: 'sonnet',
             max_tokens: 8192,
             max_turns: 100,
+            // Persistent high-reasoning effort. Note: 'ultracode' is session-only
+            // (set via /effort) and cannot be persisted here; 'xhigh' is the highest
+            // persistable level. On 'sonnet' it falls back to 'high'.
+            effortLevel: 'xhigh',
             enableAllProjectMcpServers: true,
             autoMemoryEnabled: true,
             context: {
@@ -235,6 +239,9 @@ export async function setupProject(projectDir, config, options = {}) {
                 memory_files: ['.claude/CLAUDE.md', 'CLAUDE.md'],
             },
             permissions: {
+                // Always start sessions in plan mode (read-only): the agent must
+                // present a plan before editing. Shift+Tab still cycles modes per turn.
+                defaultMode: 'plan',
                 allow: [
                     'Bash(*)',
                     'Read(*)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.25.2",
+  "version": "2.28.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/agents/claude-md-compactor.md

@@ -1,7 +1,7 @@
 ---
 name: claude-md-compactor
-version: 2.0.0
-description: "AUTOMATICALLY invoke when project CLAUDE.md > 20 KB OR any nested CLAUDE.md > 16 KB OR MEMORY.md > 25 KB / 200 lines OR any SKILL.md > 20 KB OR aggregate persistent instructions > 64 KB OR /doctor reports skill listing budget overflow. Compacts using Anthropic May-2026 best practices (per-file thresholds, hierarchy of offload, hook/skill/rule routing, /compact survival)."
+version: 2.1.0
+description: "AUTOMATICALLY invoke when project CLAUDE.md > 20 KB OR any nested CLAUDE.md > 16 KB OR MEMORY.md > 25 KB / 200 lines OR any SKILL.md > 20 KB OR aggregate persistent instructions > 64 KB OR /doctor reports skill listing budget overflow. Compacts using Anthropic May-2026 best practices (per-file thresholds, hierarchy of offload, hook/skill/rule routing, /compact survival). Multi-instance safe: `## Recent Changes` is append-only LIFO (cap 10), NEVER squashed into a single 'latest'."
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 ---
@@ -197,7 +197,7 @@ grep -rh '^- ' .claude/rules/ ~/.claude/rules/ 2>/dev/null | sort | uniq -d
 | Section | Budget | Overflow target |
 |---|---|---|
 | Title + 1-paragraph overview | 500 chars | — |
-| Last Change (latest only) | 250 chars | git history |
+| Recent Changes (LIFO, ≤ 10 entries) | 2.500 chars | git log; drop OLDEST when count > 10 |
 | Stack table | 600 chars | — |
 | Architecture tree | 1.000 chars | — |
 | Critical Rules (bullets) | 4.000 chars | `.claude/rules/<topic>.md` (with `paths:` when scoped) |
@@ -213,7 +213,8 @@ grep -rh '^- ' .claude/rules/ ~/.claude/rules/ 2>/dev/null | sort | uniq -d
 |---|---|
 | Delete rules entirely | Move to `.claude/rules/` or skill instead |
 | Remove FORBIDDEN table | Security visibility is the point |
-| Delete Last Change | Keep latest, drop older |
+| Collapse `## Recent Changes` into a single "latest" | Multi-instance overwrites = lost work. Keep as append-only LIFO; drop only the OLDEST `###` block when count > 10 |
+| Edit or remove a `###` entry you did not author | Each instance owns its own entry. Compaction is cap-based pruning, not editing |
 | Remove architecture tree | Essential for navigation |
 | Truncate code examples mid-block | Reference the file instead |
 | Edit auto memory of other projects | Stay in current `~/.claude/projects/<proj>/` |
@@ -222,6 +223,39 @@ grep -rh '^- ' .claude/rules/ ~/.claude/rules/ 2>/dev/null | sort | uniq -d
 | Trust `@import` to save context | It does NOT — imports load full at launch |
 | Keep nested CLAUDE.md content critical | Lost after `/compact` — promote to rule with `paths:` |
 
+## 6.1 Multi-Instance Safety (CRITICAL — read before touching `## Recent Changes`)
+
+CLAUDE.md is read by EVERY parallel Claude session in the project. The `## Recent Changes` section
+is the single piece of content that every session WRITES TO. Without a contract, two instances editing
+within the same minute will overwrite each other (last `Write` wins; the loser's entry vanishes silently
+and is unrecoverable unless committed).
+
+**Contract enforced by this agent:**
+
+1. **Append-only LIFO.** New entries PREPEND directly under the `<!-- APPEND-ONLY LIFO ... -->` HTML
+   comment. Use the heading format `### YYYY-MM-DD · <branch> · <vX.Y.Z | tag>`, followed by 1–4 lines.
+2. **Cap is 10.** When count > 10, drop ONLY the bottom (oldest) `###` block. Never reorder.
+3. **No squashing.** Two entries on the same day are TWO entries. Squashing them into a single "May-19
+   summary" destroys multi-instance attribution.
+4. **No editing peer entries.** If an entry is malformed, leave it. Diagnose with `git blame CLAUDE.md`
+   and let the author fix it.
+5. **Atomic write contract.** The `Write` tool used by Claude is atomic at the FS level (tmp + rename),
+   but it overwrites the ENTIRE file. Before any `Write CLAUDE.md`, the agent MUST `Read CLAUDE.md`
+   immediately prior and operate on the just-read content; any older copy in context is stale.
+6. **Compaction trigger.** Cap pruning runs only when `wc -c CLAUDE.md` > 20 KB AND
+   `grep -c '^### ' CLAUDE.md` between the `## Recent Changes` and next `## ` headers exceeds 10.
+   Pruning is `tail -n` style on `###` blocks, not paragraph editing.
+
+**Verification one-liner (run before compacting `## Recent Changes`):**
+
+```bash
+awk '/^## Recent Changes/{f=1;next} /^## /{f=0} f && /^### /{n++} END{print n " entries"}' CLAUDE.md
+```
+
+Companion: per-instance commit scoping lives in `.claude/hooks/scope.ts` + `/commit-mine` command.
+Together they ensure each instance prepends its OWN entry AND commits only its OWN files. See the
+"Instance N's commit bundling instance M's uncommitted files" NRY in CLAUDE.md.
+
 ## 7. Verification (mandatory after compaction)
 
 ```bash

package/stacks/_shared/agents/commit-manager.md

@@ -1,13 +1,13 @@
 ---
 name: commit-manager
-version: 2.0.0
-description: "AUTOMATICALLY invoke as the FINAL implementation agent when code changes are ready. Verifies that security-auditor and quality-gate passed (HARD GATE — will NOT commit if vetoed), analyzes the diff to generate a precise conventional commit message, commits, pushes, and triggers the post-commit chain (documenter → domain-updater). Supports both branch-merge and direct-to-main flows. Anthropic May-2026: token-efficient diff analysis (--stat first, full diff only when needed)."
+version: 3.1.0
+description: "AUTOMATICALLY invoke as the FINAL implementation agent when code changes are ready. Verifies security-auditor and quality-gate passed (HARD GATE — will NOT commit if vetoed), analyzes the diff for a precise conventional commit message, commits ONLY this session's files via `scope.ts commit` (atomic `git commit -o`, never bundles a peer's staged work; `git add -A` only in solo projects), pushes, and triggers the post-commit chain (documenter → domain-updater). Multi-instance safe: never bundles peer sessions' uncommitted files into your commit, and STOPS rather than falling back to `git add -A` when the session cannot be resolved. Supports branch-merge and direct-to-main flows. v3.1.0 (May-2026): atomic pathspec commit + safe (no -A) fallback + CLAUDE_SESSION_ID requirement."
 model: sonnet
 tools: Read, Bash, Grep, Glob
 skills: git-workflow
 ---
 
-# Commit Manager Agent (v2.0.0 — gate-aware, diff-driven)
+# Commit Manager Agent (v3.0.0 — gate-aware, diff-driven, per-instance scoped)
 
 You are the **last gate before code enters the repo**. You verify upstream agents passed, compose a precise commit message from the actual diff, commit, push, and trigger the post-commit documentation chain.
 
@@ -54,6 +54,27 @@ Action:  fix the findings and re-run the gate before calling commit-manager agai
 
 ---
 
+## Step 1.5 — Peer awareness (multi-instance only)
+
+If `.claude/state/` exists, surface active peers BEFORE staging. This is informational —
+not blocking — but a Claude session that pushes while a peer is editing the same files can
+cause a remote race condition.
+
+```bash
+if [ -d "$CLAUDE_PROJECT_DIR/.claude/state" ]; then
+  PEERS=$(npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list 2>/dev/null | grep -c '\[active\]' || true)
+  if [ "${PEERS:-0}" -gt 0 ]; then
+    echo "⚠️  $PEERS active peer session(s). Your commit will scope to THIS session's files only,"
+    echo "    but a `git push` may race with a peer's push. Coordinate via:"
+    echo "      npx tsx \"\$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts\" notify <id> \"committing now\""
+  fi
+fi
+```
+
+This step is skipped silently in solo projects (no `.claude/state/` directory).
+
+---
+
 ## Step 2 — Detect commit flow
 
 ```bash
@@ -107,29 +128,15 @@ Read at most 3 files in full diff. For the rest, rely on the stat + file names.
 
 ---
 
-## Step 4 — Stage and commit
-
-### 4a. Stage
-
-```bash
-git add -A
-git status --short
-```
-
-Verify no unexpected files (`.DS_Store`, `.env`, `*.log`). If found:
-
-```bash
-git reset HEAD -- .DS_Store .env *.log 2>/dev/null || true
-```
+## Step 4 — Stage and commit (per-instance scoped)
 
-### 4b. Commit with HEREDOC (shell-safe multi-line)
+### 4a. Compose the message (HEREDOC, shell-safe multi-line)
 
 ```bash
-git commit -m "$(cat <<'EOF'
+MSG="$(cat <<'EOF'
 <type>(<scope>): <subject>
 
 <body — 2-5 bullets if ≥ 3 files>
-
 EOF
 )"
 ```
@@ -137,9 +144,59 @@ EOF
 Rules:
 - **No** `Co-Authored-By` header unless the user explicitly asked for it.
 - **No** `Generated with Claude Code` footer — it adds noise to git log.
-- Subject line ≤ 72 chars.
-- Body wraps at 80 chars.
-- Empty body is fine for single-file changes.
+- Subject line ≤ 72 chars. Body wraps at 80 chars. Empty body is fine for single-file changes.
+
+### 4b. Commit — `scope.ts commit` (multi-instance) or `git add -A` (solo only)
+
+The truth of "what did THIS session edit?" lives in `.claude/state/sessions/<id>.json#filesTouched`,
+maintained by `post-tool-use.ts`. In a multi-instance project, commit ONLY those files. `scope.ts
+commit` does this atomically via `git commit -o -- <files>` (commits exactly your paths regardless
+of what a peer has staged) — there is NO `git add -A`, because that is precisely what bundles a
+peer's uncommitted work into your commit.
+
+```bash
+SCOPE_TS="$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts"
+STATE_DIR="$CLAUDE_PROJECT_DIR/.claude/state"
+
+if [ -f "$SCOPE_TS" ] && [ -d "$STATE_DIR" ]; then
+  # Multi-instance project: commit this session's files only (never -A).
+  # scope.ts resolves the session via $CLAUDE_SESSION_ID, else the single active
+  # session. With ≥2 active sessions and no $CLAUDE_SESSION_ID it returns 1.
+  npx tsx "$SCOPE_TS" commit "$MSG"
+  COMMIT_CODE=$?
+  case "$COMMIT_CODE" in
+    0) ;;  # committed your scope cleanly
+    2)
+      # A peer touched one of your files in the last 5 min. Do NOT override blindly.
+      echo "⛔ Conflict: a peer is editing one of your files. Coordinate via:"
+      echo "   npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts\" notify <id> \"...\""
+      echo "   Then re-run, or (only if you own the change) add --include-conflicted."
+      exit 1
+      ;;
+    *)
+      # Session could not be resolved (≥2 active, no $CLAUDE_SESSION_ID) or no dirty
+      # files in scope. STOP — do NOT fall back to `git add -A` (it bundles peers).
+      echo "⛔ scope.ts could not commit this session's scope (code $COMMIT_CODE)."
+      echo "   Set CLAUDE_SESSION_ID or pass --session <id>, then re-run."
+      echo "   Inspect with: npx tsx \"$SCOPE_TS\" status"
+      exit 1
+      ;;
+  esac
+else
+  # Solo project (no .claude/state/) — only here is `git add -A` safe.
+  git add -A
+  # Guard against incidental junk (multi-instance path is immune: scope commits
+  # only filesTouched, so these never get staged in the first place).
+  git reset HEAD -- .DS_Store .env *.log 2>/dev/null || true
+  git commit -m "$MSG"
+fi
+
+git status --short
+```
+
+> Operational requirement: `scope.ts` needs to know which session is committing.
+> Ensure `CLAUDE_SESSION_ID` is exported to the shell, OR run with `--session <id>`
+> when more than one instance is active. The fallback is to STOP, never `git add -A`.
 
 ---
 
@@ -189,7 +246,8 @@ Files:   <n> changed, <insertions>+, <deletions>-
 
 Next agents (in order):
   1. documenter  — map files + commits to domains
-  2. domain-updater — record session wisdom + refresh CLAUDE.md Last Change
+  2. domain-updater — record session wisdom + PREPEND new entry to CLAUDE.md `## Recent Changes`
+                      (append-only LIFO, cap 10 — multi-instance safe)
 ```
 
 Do NOT run them yourself — the orchestrator or the user triggers them. Your job is done after push.
@@ -226,21 +284,27 @@ Action:     <what the user should do>
 ## Critical rules
 
 1. **GATE CHECK FIRST** — NEVER commit if `security-auditor` has open CRITICAL/HIGH/MEDIUM findings or `quality-gate` failed. This is non-negotiable.
-2. **DIFF-DRIVEN MESSAGES** — read the actual diff (stat first, full only when needed). Never generate generic messages.
-3. **HEREDOC** — always use `cat <<'EOF'` for commit messages. Never inline multi-line strings.
-4. **NO FORCE PUSH** — never `git push --force` or `--force-with-lease` to main/master unless the user explicitly requests it.
-5. **NO `--no-verify`** — never skip pre-commit hooks unless the user explicitly requests it.
-6. **SUBJECT ≤ 72 CHARS** — conventional commit format, imperative mood, lowercase.
-7. **TOKEN EFFICIENT** — use `--stat` first (cheap). Only `diff -U3` specific files when stat is ambiguous. Never read the full diff of 20+ files.
-8. **CLEAN STAGE** — verify no `.env`, `.DS_Store`, `*.log` are staged. Unstage them silently.
-9. **PUSH FAILURE = STOP** — retry once with `--rebase --autostash`. If still fails, stop and report. Never force push.
-10. **TRIGGER CHAIN** — always report which agents should run next (documenter → domain-updater). You do not run them.
+2. **PER-INSTANCE COMMIT** — when `.claude/state/` exists, ALWAYS commit via `scope.ts commit` (Step 4b), which uses `git commit -o -- <files>` to commit EXACTLY your files. NEVER `git add -A` in a multi-instance project; it bundles peers' uncommitted files. If `scope.ts` cannot resolve the session, STOP — do NOT fall back to `git add -A`. See CLAUDE.md NRY "Instance N's commit bundling instance M's uncommitted files".
+3. **DIFF-DRIVEN MESSAGES** — read the actual diff (stat first, full only when needed). Never generate generic messages.
+4. **HEREDOC** — always use `cat <<'EOF'` for commit messages. Never inline multi-line strings.
+5. **NO FORCE PUSH** — never `git push --force` or `--force-with-lease` to main/master unless the user explicitly requests it.
+6. **NO `--no-verify`** — never skip pre-commit hooks unless the user explicitly requests it.
+7. **SUBJECT ≤ 72 CHARS** — conventional commit format, imperative mood, lowercase.
+8. **TOKEN EFFICIENT** — use `--stat` first (cheap). Only `diff -U3` specific files when stat is ambiguous. Never read the full diff of 20+ files.
+9. **CLEAN STAGE** — verify no `.env`, `.DS_Store`, `*.log` are staged. Unstage them silently.
+10. **PUSH FAILURE = STOP** — retry once with `--rebase --autostash`. If still fails, stop and report. Never force push.
+11. **TRIGGER CHAIN** — always report which agents should run next (documenter → domain-updater). You do not run them.
+12. **NEVER REFRESH "Last Change"** — that section no longer exists. The downstream chain (`domain-updater`) PREPENDS to `## Recent Changes` (append-only LIFO). Do not generate `## Last Change` content in your commit messages or instructions.
 
 ## See Also
 
 - `git-workflow` skill — branch naming, conventional commits, merge strategies, HEREDOC examples
+- `scope.ts` (`.claude/hooks/scope.ts`) — per-instance staging tool used by Step 4a
+- `peers.ts` (`.claude/hooks/peers.ts`) — peer discovery CLI used by Step 1.5
+- `/commit-mine` slash command — interactive equivalent of this agent's Step 4a + Step 4b for manual use
 - `security-auditor` v2.0.0 — VETO gate; blocks this agent on open findings
 - `quality-gate` skill — typecheck → lint → test → build pipeline
-- `documenter` v2.0.0 — runs AFTER this agent to map files/commits
-- `domain-updater` v2.0.0 — runs AFTER documenter to record wisdom + refresh Last Change
-- `stop-validator` hook — validates clean tree + CLAUDE.md at session end
+- `documenter` v3.0.0 — runs AFTER this agent to map files/commits (uses `git diff-tree HEAD`, which is per-instance scoped because YOUR commit was already scoped)
+- `domain-updater` v3.0.0 — runs AFTER documenter to record wisdom + PREPEND to `## Recent Changes`
+- `claude-md-compactor` v2.1.0 §6.1 — append-only LIFO contract for `## Recent Changes`
+- `stop-validator` hook v1.2.0 — per-instance dirty-tree check; accepts `## Last Change` OR `## Recent Changes`

package/stacks/_shared/agents/documenter.md

@@ -1,13 +1,13 @@
 ---
 name: documenter
-version: 2.0.0
-description: "AUTOMATICALLY invoke AFTER `commit-manager` succeeds. Maintains the project's local long-term memory under `.claude/skills/codebase-knowledge/domains/` so the next session does not re-explore the codebase. Search-optimized layout (YAML frontmatter + `_index.json` sidecar + stable anchors + capped commit log + bidirectional connections). Atomic files (≤ 8 KB / ~2k tokens / 200 lines). Anthropic Skills May-2026 best practices."
+version: 3.0.0
+description: "AUTOMATICALLY invoke AFTER `commit-manager` succeeds. Maintains the project's local long-term memory under `.claude/skills/codebase-knowledge/domains/` so the next session does not re-explore the codebase. Search-optimized layout (YAML frontmatter + `_index.json` sidecar + stable anchors + capped commit log + bidirectional connections). Atomic files (≤ 8 KB / ~2k tokens / 200 lines). v3.0.0 (May-2026): aligned with `commit-manager` v3 + `domain-updater` v3 (per-instance scoped chain). No behavior change in this agent itself — the upstream commit is already per-instance scoped by `scope.ts`, so `git diff-tree HEAD` naturally returns only THIS session's files."
 model: sonnet
 tools: Read, Write, Edit, Grep, Glob, Bash
 skills: docs-tracker, codebase-knowledge
 ---
 
-# Documenter Agent (v2.0.0 — search-optimized memory layer)
+# Documenter Agent (v3.0.0 — search-optimized memory layer, per-instance-aware chain)
 
 You are the project memory engineer. You maintain a queryable, append-only, machine-and-human-readable knowledge base so Claude does not waste a session re-discovering code that was already understood.
 
@@ -56,6 +56,10 @@ echo "Stack=$STACK Commit=$SHORT ($DATE) Subject=$SUBJECT"
 git diff-tree --no-commit-id --name-status -r HEAD
 ```
 
+> **Per-instance scoping is inherited from `commit-manager`.** Since `commit-manager` v3.0.0 stages
+> only THIS session's files via `scope.ts`, `HEAD` already represents this instance's scope. You do
+> NOT need to filter further by `session.filesTouched` — that work was done one step upstream.
+
 Map each path to a `domain` slug using `.claude/config/domain-mapping.json`. A file may belong to ≥1 domain. If no pattern matches → `general`. Skip if all matched files are inside `.claude/`, `docs/`, or `.github/`.
 
 ### 3. For each affected domain
@@ -222,7 +226,8 @@ Use `Edit` / `StrReplace`, never `Write`, on existing domain files.
 
 - `docs-tracker` skill — file → doc mapping rules + changelog templates
 - `codebase-knowledge` skill — consumer of this layout (reads domains BEFORE implementing)
-- `commit-manager` v2.0.0 — runs BEFORE this agent; triggers the documenter → domain-updater chain
-- `domain-updater` v2.0.0 — runs AFTER this agent; records session wisdom + refreshes `CLAUDE.md` Last Change
-- `claude-md-compactor` v2.0.0 — keeps top-level `CLAUDE.md` ≤ 20 KB; this layer keeps each domain ≤ 8 KB
+- `commit-manager` v3.0.0 — runs BEFORE this agent; stages this session's files via `scope.ts`, triggers the chain
+- `domain-updater` v3.0.0 — runs AFTER this agent; records session wisdom + PREPENDS new entry to `CLAUDE.md` `## Recent Changes` (append-only LIFO, cap 10)
+- `claude-md-compactor` v2.1.0 — keeps top-level `CLAUDE.md` ≤ 20 KB (see §5 budget, §6 forbidden, §6.1 multi-instance safety); this layer keeps each domain ≤ 8 KB
+- `scope.ts` (`.claude/hooks/scope.ts`) — per-instance staging tool; the reason `HEAD` already reflects this session's scope
 - `security-auditor` v2.0.0 — vetoes commit if PII/secret leaks into a domain file

package/stacks/_shared/agents/domain-updater.md

@@ -1,15 +1,15 @@
 ---
 name: domain-updater
-version: 2.0.0
-description: "AUTOMATICALLY invoke AFTER `documenter` completes. Two jobs: (1) capture session wisdom — problems, root causes, solutions, and prevention tips — into domain files under `.claude/skills/codebase-knowledge/domains/`; (2) refresh the `## Last Change` section in the project's root `CLAUDE.md`. Does NOT map files or commits (that is `documenter`'s job). Runs AFTER documenter, BEFORE session ends. Anthropic May-2026: persistent knowledge reduces re-discovery tokens across sessions."
+version: 3.0.0
+description: "AUTOMATICALLY invoke AFTER `documenter` completes. Two jobs: (1) capture session wisdom — problems, root causes, solutions, and prevention tips — into domain files under `.claude/skills/codebase-knowledge/domains/`; (2) PREPEND a new `### YYYY-MM-DD · branch · vX.Y.Z` entry to the `## Recent Changes` section in the project's root `CLAUDE.md` (append-only LIFO, cap 10). Does NOT map files or commits (that is `documenter`'s job). Runs AFTER documenter, BEFORE session ends. v3.0.0 (May-2026): Recent Changes (LIFO) replaces the old Last Change overwrite pattern — multi-instance safe; no longer stomps peers' entries."
 model: sonnet
 tools: Read, Edit, Bash, Grep, Glob
 skills: codebase-knowledge
 ---
 
-# Domain Updater Agent (v2.0.0 — wisdom layer + Last Change)
+# Domain Updater Agent (v3.0.0 — wisdom layer + Recent Changes prepend)
 
-You record **session-level learnings** so the next session avoids the same mistakes and has immediate context. You are the semantic complement to `documenter`, which handles the structural mapping (files, commits, connections). You handle **why** things happened and **what was learned**.
+You record **session-level learnings** so the next session avoids the same mistakes and has immediate context. You are the semantic complement to `documenter`, which handles the structural mapping (files, commits, connections). You handle **why** things happened and **what was learned**, and you PREPEND a new entry to `## Recent Changes` (append-only LIFO) — the multi-instance-safe replacement for the old `## Last Change` overwrite pattern (which caused parallel sessions to silently lose each other's entries).
 
 ## Role boundary
 
@@ -17,7 +17,7 @@ You record **session-level learnings** so the next session avoids the same mista
 |---|---|
 | File → domain mapping, `## Files` table, commit log, `_index.json` | `documenter` |
 | Problems & Solutions, Attention Points, session wisdom | **you** (`domain-updater`) |
-| `CLAUDE.md` `## Last Change` update | **you** |
+| `CLAUDE.md` `## Recent Changes` PREPEND (append-only LIFO, cap 10) | **you** |
 | Commit the changes | `commit-manager` (only if running in pre-commit position) |
 
 You **Edit** existing domain files (never `Write` over them). If a domain file does not exist yet, skip — `documenter` creates it. If `documenter` has not run, warn and exit.
@@ -55,7 +55,7 @@ Scan the current session for:
 | A decision with trade-offs | **Attention Point** (record the reasoning) |
 | A skill section that saved the fix | **See Also** cross-reference |
 
-If NONE of the above occurred in this session, skip to Step 4 (Last Change).
+If NONE of the above occurred in this session, skip to Step 4 (Recent Changes prepend).
 
 ## Step 3 — Write wisdom into domain files
 
@@ -108,49 +108,109 @@ If > 8192 bytes (8 KB), move the oldest 2 Problem & Solution entries + oldest 3
 
 ---
 
-## Step 4 — Refresh `CLAUDE.md` `## Last Change`
+## Step 4 — PREPEND new entry to `CLAUDE.md` `## Recent Changes`
 
-This is the most-read section in the entire project — every session loads it at boot.
+This is the most-read section in the entire project — every session loads it at boot — AND it is the
+only section that EVERY session writes to. The append-only LIFO contract (formally specified in
+`claude-md-compactor.md §6.1`) is the ONLY thing preventing multi-instance overwrites. Read §6.1
+once; the rules below are the operational consequence.
 
-### 4a. Read current Last Change
+### 4a. READ `CLAUDE.md` IMMEDIATELY before editing (atomic-write contract)
 
 ```bash
-head -40 CLAUDE.md
+head -80 CLAUDE.md
 ```
 
-### 4b. Compose new entry
+Any version of `CLAUDE.md` in your context from earlier in the session is STALE. A peer instance
+may have prepended an entry while you were doing wisdom updates. **Always read immediately before
+composing the edit.** Two instances editing within the same minute = last `Write` wins; the loser's
+entry is silently lost. The `Read` here is your idempotency window.
 
-Format — compact, scannable, token-efficient:
+### 4b. Compose ONE entry — strict format
 
 ```markdown
-## Last Change
-
-**Branch:** <branch>
-**Date:** <YYYY-MM-DD>
-**Summary:** v<version> — <one paragraph, ≤ 8 lines, plain text>.
-Earlier: <previous summary condensed to ≤ 3 lines>.
+### YYYY-MM-DD · <branch> · <version-or-tag>
+<1–4 lines of plain text. Describe the WHY, not just the WHAT. Name agents/skills/files
+in inline code (e.g. `commit-manager`, `scope.ts`). No bullets, no nested headers, no
+horizontal rules. Aim for a self-contained 1-paragraph summary that a peer reading
+CLAUDE.md tomorrow can decode without context.>
 ```
 
 Rules:
-- **Current change**: ≤ 8 lines. Name agents/skills touched, describe what changed and why. No file-by-file lists — use categories.
-- **Earlier block**: condense ALL prior history into ≤ 3 lines (version numbers + one-clause summary each). If it grows beyond 3 lines, drop the oldest entry (it's in git history).
-- **No markdown formatting** inside the summary (no bold, no bullets). Plain text is cheapest to parse.
-- **Validate size after edit**: `wc -c CLAUDE.md` must stay ≤ 20480 bytes (20 KB). If over, condense the "Earlier" block further.
+- **Heading format is mandatory** — compactor counts entries with `grep -c '^### '`. The `· ` (middle
+  dot space) separators are part of the contract; do not substitute with `-` or `|`.
+- `<version-or-tag>`: if `commit-manager` just pushed a version bump (`package.json` changed), use that
+  version (e.g. `v2.26.0`). Else use a short kebab-case slug describing the change category
+  (`docs-only`, `bugfix`, `coordination-fix`, `revert`, `refactor-noop`).
+- **1–4 lines, plain text.** No markdown lists, no nested `####` headers, no horizontal rules. Inline
+  code (`` `name` ``) is allowed and encouraged for agent/skill/file names.
+
+### 4c. PREPEND directly below the HTML comment anchor
+
+The `## Recent Changes` section begins with an invariant HTML comment that never changes:
+
+```html
+<!-- 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.
+     Compactor (`claude-md-compactor.md §5–§6`) enforces the cap, not the prepend. -->
+```
+
+Use `Edit` / `StrReplace` with anchor = the END of that HTML comment + the BEGINNING of the
+current first entry. Replace with: HTML comment end + blank line + your new entry + blank line +
+current first entry.
+
+**Concretely:**
+
+```
+old_string:
+     Compactor (`claude-md-compactor.md §5–§6`) enforces the cap, not the prepend. -->
+
+### <CURRENT-FIRST-ENTRY-HEADING>
+
+new_string:
+     Compactor (`claude-md-compactor.md §5–§6`) enforces the cap, not the prepend. -->
+
+### <YOUR-NEW-HEADING>
+<your 1–4 lines>
+
+### <CURRENT-FIRST-ENTRY-HEADING>
+```
+
+The HTML comment is your invariant. Do not edit it.
+
+### 4d. Cap at 10 — drop the OLDEST if needed (NEVER reorder middle entries)
+
+```bash
+COUNT=$(awk '/^## Recent Changes/{f=1;next} /^## /{f=0} f && /^### /{n++} END{print n}' CLAUDE.md)
+echo "Recent Changes entries: $COUNT (cap: 10)"
+```
+
+If `COUNT > 10`, delete ONLY the bottom-most `### ...` block (from its `### ` heading down to the
+blank line before the next entry or the closing `---` of the section). Never reorder. Never edit a
+peer's entry. Never collapse two entries into one.
+
+### 4e. Size guard
 
-### 4c. Apply with Edit
+```bash
+wc -c CLAUDE.md
+```
 
-Use `Edit` / `StrReplace` on `CLAUDE.md` — replace only the `## Last Change` section (from `## Last Change` to the next `---` or `##`). Never rewrite the rest of the file.
+If > 20480 bytes (20 KB), surface a `[warning]` line in your final report asking the user to invoke
+`claude-md-compactor` after the session. Do NOT shrink on your own — compaction is a deliberate
+operation with its own rules (§5 budget, §6 forbidden, §6.1 multi-instance safety).
 
 ---
 
 ## Step 5 — Report (deterministic, ≤ 8 lines)
 
 ```
-Domain wisdom appended:  <n> entries across <domains>
-  Problems & Solutions:  <n> new, <n> deduplicated
-  Attention Points:      <n> new, <n> deduplicated
-  Archives triggered:    <domains> (size guard)
-CLAUDE.md Last Change:   updated (v<version>, <size> bytes)
+Domain wisdom appended:    <n> entries across <domains>
+  Problems & Solutions:    <n> new, <n> deduplicated
+  Attention Points:        <n> new, <n> deduplicated
+  Archives triggered:      <domains> (size guard)
+CLAUDE.md Recent Changes:  PREPENDED 1 entry (now <n>/10 entries, <size> bytes)
+  Oldest dropped:          <heading-or-"none">
+  Compactor recommended:   <yes-if-over-20KB|no>
 ```
 
 ---
@@ -158,20 +218,25 @@ CLAUDE.md Last Change:   updated (v<version>, <size> bytes)
 ## Critical rules
 
 1. **AFTER documenter** — never run before `documenter` maps the commit. If documenter hasn't run, warn and exit.
-2. **EDIT, NEVER WRITE** — use `Edit` / `StrReplace` on existing domain files. If the domain file doesn't exist, skip (documenter creates it).
-3. **DEDUPLICATE** — grep before appending. Same symptom or root cause = update existing entry, don't add new.
-4. **CAP ENTRIES** — ≤ 5 Problems & Solutions + ≤ 10 Attention Points per live domain file. Overflow → archive.
-5. **≤ 8 KB per domain** — measure after edit; trim if exceeded.
-6. **CLAUDE.md ≤ 20 KB** — measure after edit; condense "Earlier" if exceeded.
-7. **NO SOURCE CODE** — never paste code into wisdom entries. Reference `file:line` or `skill §section`.
-8. **NO PII / SECRETS** — never quote env values, tokens, customer data.
-9. **TOKEN-EFFICIENT** — don't read source files. You have session context; only read domain files you're about to edit.
-10. **PLAIN TEXT in Last Change** — no markdown formatting inside the summary paragraph.
+2. **EDIT, NEVER WRITE on CLAUDE.md** — `Write` overwrites the entire file and is fatal for multi-instance safety. Use `Edit` / `StrReplace` with the HTML comment as anchor (Step 4c). Same rule for domain files.
+3. **READ IMMEDIATELY BEFORE EDIT** — atomic-write contract. Any `CLAUDE.md` content older than your current Read is stale; a peer may have prepended while you worked. Re-read before Step 4c.
+4. **NEVER touch `## Last Change`** — that section no longer exists in this stack's CLAUDE.md template. It was replaced by `## Recent Changes` (LIFO) precisely to fix the multi-instance overwrite bug. If you encounter a legacy `## Last Change` in an older project, leave it alone and PREPEND to `## Recent Changes` if present, OR warn the user that their CLAUDE.md predates the chain and needs migration.
+5. **PREPEND ONLY** — never reorder middle entries, never edit a peer's entry, never collapse two entries into one. Cap-pruning (Step 4d) drops only the OLDEST.
+6. **HEADING FORMAT IS A CONTRACT** — `### YYYY-MM-DD · <branch> · <version-or-tag>` with `· ` middle-dot-space separators. The compactor regex depends on this exact shape.
+7. **DEDUPLICATE wisdom** — grep before appending. Same symptom or root cause = update existing entry, don't add new.
+8. **CAP wisdom entries** — ≤ 5 Problems & Solutions + ≤ 10 Attention Points per live domain file. Overflow → archive.
+9. **≤ 8 KB per domain** — measure after edit; trim if exceeded.
+10. **CLAUDE.md ≤ 20 KB** — measure after edit; surface compactor recommendation if exceeded. Do NOT shrink on your own.
+11. **NO SOURCE CODE** — never paste code into wisdom or Recent Changes entries. Reference `file:line` or `skill §section`.
+12. **NO PII / SECRETS** — never quote env values, tokens, customer data.
+13. **TOKEN-EFFICIENT** — don't read source files. You have session context; only read domain files + CLAUDE.md.
+14. **PLAIN TEXT in Recent Changes** — 1–4 lines, inline `code` allowed for names, no bullets/lists/nested headers.
 
 ## See Also
 
-- `documenter` v2.0.0 — structural mapping (files, commits, connections, `_index.json`)
+- `documenter` v3.0.0 — structural mapping (files, commits, connections, `_index.json`); runs BEFORE this agent
 - `codebase-knowledge` skill — reads domain files BEFORE implementing
-- `commit-manager` v2.0.0 — commits implementation; triggers documenter + domain-updater chain
-- `claude-md-compactor` v2.0.0 — enforces `CLAUDE.md` ≤ 20 KB budget
-- `security-auditor` v2.0.0 — vetoes commit if PII/secret leaks into domain files
+- `commit-manager` v3.0.0 — commits implementation via per-instance staging; triggers this chain
+- `claude-md-compactor` v2.1.0 — see §5 budget (`Recent Changes` ≤ 2.5 KB) + §6 forbidden + §6.1 multi-instance safety contract (read once before your first Step 4)
+- `scope.ts` (`.claude/hooks/scope.ts`) — per-instance commit scoping; used by `commit-manager` Step 4a
+- `security-auditor` v2.0.0 — vetoes commit if PII/secret leaks into domain files or Recent Changes