start-vibing-stacks 2.25.2 → 2.26.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.25.2",
+  "version": "2.26.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.0.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, stages ONLY this session's files via `scope.ts` when state is available (falls back to `git add -A` for solo projects), commits, pushes, and triggers the post-commit chain (documenter → domain-updater). Multi-instance safe: never bundles peer sessions' uncommitted files into your commit. Supports branch-merge and direct-to-main flows. v3.0.0 (May-2026): per-instance scoped staging + Recent Changes (LIFO) chain alignment."
 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,12 +128,43 @@ Read at most 3 files in full diff. For the rest, rely on the stat + file names.
 
 ---
 
-## Step 4 — Stage and commit
+## Step 4 — Stage and commit (per-instance scoped)
 
-### 4a. Stage
+### 4a. Stage — `scope.ts` first, `git add -A` as fallback
+
+The truth of "what did THIS session edit?" lives in `.claude/state/sessions/<id>.json#filesTouched`,
+maintained by `post-tool-use.ts`. Stage from that, NOT from the worktree at large — otherwise
+you risk bundling a peer session's uncommitted files into your commit.
 
 ```bash
-git add -A
+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: stage this session's files only.
+  npx tsx "$SCOPE_TS" stage
+  STAGE_CODE=$?
+  case "$STAGE_CODE" in
+    0)
+      # All safe files staged. Continue.
+      ;;
+    2)
+      # Some safe files staged; conflicted ones skipped intentionally.
+      # scope.ts already printed the warning. Continue — committing the safe scope is correct.
+      echo "ℹ️  Conflicted files skipped (peer also touched in last 5 min). Proceeding with safe scope."
+      ;;
+    *)
+      # scope.ts couldn't resolve session or found no dirty files in scope.
+      # Fall back to legacy behavior — should NOT happen in a healthy multi-instance project.
+      echo "⚠️  scope.ts returned $STAGE_CODE; falling back to legacy `git add -A` (multi-instance risk!)"
+      git add -A
+      ;;
+  esac
+else
+  # Solo project (no .claude/state/) — legacy flow is correct.
+  git add -A
+fi
+
 git status --short
 ```
 
@@ -189,7 +241,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 +279,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 STAGING** — when `.claude/state/` exists, ALWAYS stage via `scope.ts` (Step 4a). NEVER `git add -A` blindly in a multi-instance project; it bundles peers' uncommitted files into your commit. 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

package/stacks/_shared/commands/commit-mine.md

@@ -0,0 +1,73 @@
+---
+name: commit-mine
+description: Commit ONLY this Claude session's edited files (multi-instance safe). Replaces raw `git add . && git commit` to prevent your commit from bundling a peer session's uncommitted changes.
+version: 1.0.0
+---
+
+# /commit-mine — Per-Instance Commit
+
+**Why this exists:** when two or more Claude sessions run in the same repo, `git add .` /
+`git add -A` / `git add -u` pick up files modified by peer sessions and bundle them into
+your commit. The peer then loses attribution and the commit becomes impossible to revert
+cleanly. This command stages and commits ONLY the files your session actually edited.
+
+**Source of truth:** `.claude/state/sessions/<your-id>.json#filesTouched`, maintained by
+`post-tool-use.ts` (one entry per successful Edit / Write / MultiEdit / NotebookEdit).
+
+| # | Step | Tool |
+|---|---|---|
+| 1 | **Inspect scope** — list SAFE / CONFLICTED / NOT-YOURS / STAGED | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" status` |
+| 2 | **Resolve conflicts** if any (peer touched same file in last 5 min) | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify <id> "msg"` |
+| 3 | **Stage** — `git reset` then `git add` only this session's dirty files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" stage` |
+| 4 | **Review** — confirm the staged diff is what you expect | `git diff --cached --stat` and (optionally) `git diff --cached` |
+| 5 | **Commit** — conventional message (`feat`, `fix`, `docs`, etc.) + diff-driven body | `git commit -m "<message>"` OR delegate to `commit-manager` agent |
+| 6 | **Push** (optional) | `git push` |
+
+## Shortcut (single command)
+
+If steps 1–5 are routine and you already know what you edited:
+
+```bash
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>" [--push]
+```
+
+This runs stage + commit (+ optional push) atomically. It will REFUSE to proceed if a
+peer touched any of your files in the last 5 min unless you pass `--include-conflicted`.
+
+## Forbidden patterns (NEVER do these in a multi-instance project)
+
+| Command | Why forbidden |
+|---|---|
+| `git add .` | Pulls in every dirty file in the worktree, including a peer's |
+| `git add -A` | Same — adds all tracked AND untracked |
+| `git add -u` | Adds every tracked modification, including a peer's |
+| `git commit -am "..."` | Implicit `-a` = `git add -u`, same problem |
+
+If you intentionally want to commit a peer's file (e.g. you're closing their session for them
+because they crashed), use `scope stage --include-conflicted` and document WHY in the commit body.
+
+## Exit codes (when scripting around it)
+
+| Code | Meaning |
+|---|---|
+| `0` | Staged / committed cleanly |
+| `1` | Argument or state error (no session, no dirty files in scope, git failed) |
+| `2` | Conflict refusal — peer touched a file in the last 5 min; pass `--include-conflicted` or coordinate |
+
+## What gets staged, precisely
+
+```
+session.filesTouched   ∩   git status (dirty + untracked)   \   peer-touched-in-last-5min
+```
+
+Files in `filesTouched` that are no longer dirty (you reverted the change) are skipped.
+Files dirty in the worktree but never touched by your session (a peer's edits, or your own
+manual edits not via Claude tools) are skipped — they appear in `status` under NOT-YOURS.
+
+## Where this fits in the broader workflow
+
+- `/fix` step 7 ("Commit") and `/feature` workflows that previously implied `git add .`
+  should now route through `/commit-mine` whenever `peers.ts list` shows ≥ 1 peer.
+- The `commit-manager` agent (if used) MUST call `scope stage` before any `git commit`
+  in a multi-instance project.
+- See `CLAUDE.md` NRY: "Instance N's commit bundling instance M's uncommitted files".

package/stacks/_shared/commands/feature.md

@@ -1,7 +1,7 @@
 ---
 name: feature
 description: Start a new feature with the full workflow (research → plan → implement → test → security → quality → commit → docs).
-version: 1.0.0
+version: 1.1.0
 ---
 
 # /feature — Start New Feature
@@ -20,6 +20,8 @@ Execute in order — do not skip steps. Steps 5–6 have **VETO power** over com
 | 6 | **Quality** — typecheck → lint → test → build | `quality-gate` |
 | 7 | **Commit** — gate-aware, diff-driven message | `commit-manager` |
 | 8 | **Map** — files + commits → domains | `documenter` |
-| 9 | **Wisdom + Last Change** — record learnings, refresh `CLAUDE.md` | `domain-updater` |
+| 9 | **Wisdom + Recent Changes** — record learnings, PREPEND new `### YYYY-MM-DD · branch · vX.Y.Z` entry to `CLAUDE.md` `## Recent Changes` (append-only LIFO, cap 10) | `domain-updater` |
 
 If `security-auditor` returns CRITICAL/HIGH/MEDIUM, fix before re-running step 5. Steps 8–9 run AFTER push and never before.
+
+**Multi-instance note:** `commit-manager` v3.0.0 stages only THIS session's files via `scope.ts` when `.claude/state/` is present — peers' uncommitted files are never bundled into your commit. For a manual / interactive equivalent of Step 7, use `/commit-mine` (skip `/feature` from Step 7 onward).

package/stacks/_shared/commands/fix.md

@@ -1,7 +1,7 @@
 ---
 name: fix
 description: Fix a bug — reproduce, isolate, minimal fix, regression test, security check, commit, record wisdom.
-version: 1.0.0
+version: 1.1.0
 ---
 
 # /fix — Fix Bug
@@ -16,8 +16,10 @@ Always read `.claude/config/active-project.json` first.
 | 4 | **Verify** — re-run the regression test + the wider suite | `tester` |
 | 5 | **Security** — only if the bug touched auth / input / secrets / SSRF surface | `security-auditor` (VETO) |
 | 6 | **Quality gate** — typecheck → lint → test → build | `quality-gate` |
-| 7 | **Commit** — `fix(scope): <subject>`, diff-driven body | `commit-manager` |
-| 8 | **Map** — files + commit → domain | `documenter` |
-| 9 | **Wisdom** — append to domain `## Problems & Solutions` (symptom + root cause + fix + prevention + skill ref) | `domain-updater` |
+| 7 | **Commit** — `fix(scope): <subject>`, diff-driven body, per-instance scoped staging | `commit-manager` v3.0.0 |
+| 8 | **Map** — files + commit → domain | `documenter` v3.0.0 |
+| 9 | **Wisdom + Recent Changes entry** — append to domain `## Problems & Solutions` (symptom + root cause + fix + prevention + skill ref) AND PREPEND `### YYYY-MM-DD · branch · fix-tag` to `CLAUDE.md` `## Recent Changes` | `domain-updater` v3.0.0 |
 
 `domain-updater` deduplicates by symptom/root-cause. If the same bug recurred, it appends a "Recurrence" note instead of a duplicate entry.
+
+**Multi-instance note:** Step 7 stages only THIS session's files via `scope.ts` when `.claude/state/` is present (peers' uncommitted files are never bundled). For a manual / interactive Step 7 (no chain auto-trigger), use `/commit-mine` instead.