start-vibing-stacks 2.25.2 → 2.28.0

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

@@ -0,0 +1,78 @@
+---
+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.1.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).
+
+**Recommended (single atomic command):**
+
+```bash
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>" [--push]
+```
+
+This commits ONLY your session's files via `git commit -o -- <files>` — it commits
+exactly your paths regardless of what a peer has staged, so it can never bundle their
+work, and it never runs a global `git reset`. It REFUSES if a peer touched any of your
+files in the last 5 min unless you pass `--include-conflicted`.
+
+**Step-by-step (when you want to review first):**
+
+| # | 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 | **Review** the diff of your files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" diff` |
+| 4 | **Commit** — atomic, only your files | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/scope.ts" commit "<message>"` |
+| 5 | **Push** (optional) | add `--push` to step 4, or `git push` |
+
+> `scope stage` still exists for manual index inspection, but it is best-effort in a
+> shared worktree (a peer's staged files can linger). Prefer `scope commit` — it is the
+> only path that is atomic against a concurrent peer.
+
+## 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 commit via `scope commit` (never `git add -A`)
+  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.

package/stacks/_shared/hooks/_state.README.md

@@ -26,8 +26,8 @@ When two or more Claude Code instances run in the same project folder, the hooks
 
 | Last activity | State    | Effect                                                                      |
 | ------------- | -------- | --------------------------------------------------------------------------- |
-| < 60s         | active   | Counts for collision detection. PreToolUse may **block** Edit/Write.        |
-| 60s – 30min   | idle     | Surfaced as a warning in `systemMessage`. Edits are **not** blocked.        |
+| < 180s        | active   | Counts for collision detection. PreToolUse may **block** Edit/Write.        |
+| 180s – 30min  | idle     | Surfaced as a warning in `systemMessage`. Edits are **not** blocked.        |
 | > 30min       | stale    | Auto-archived on the next sweep.                                            |
 | > 24h         | removed  | Deleted entirely.                                                           |
 

package/stacks/_shared/hooks/_state.ts

@@ -1,4 +1,4 @@
-// @sv-version: 1.0.0
+// @sv-version: 1.1.0
 /**
  * Multi-Instance Coordination — Shared State Library
  *
@@ -16,7 +16,13 @@
  * Design rules:
  * - All writes are atomic (.tmp + rename) where the file is read by peers.
  * - Every read tolerates corruption (try/catch) — hooks must NEVER block Claude.
- * - Heartbeat thresholds: <60s active, 60s-30min idle, >30min stale, >24h removed.
+ * - Heartbeat thresholds: <180s active, 180s-30min idle, >30min stale, >24h removed.
+ *
+ * v1.1.0: ACTIVE window 60s→180s (agent think/generate time between tool calls
+ * routinely exceeds 60s — a 60s window mis-classifies busy peers as IDLE);
+ * FILES_TOUCHED_CAP 50→200 (large sessions were dropping early edits, which then
+ * showed up as orphaned dirty files a peer could not attribute); path
+ * normalization in extractTargetFiles is now repo-root-stable.
  */
 
 import {
@@ -33,18 +39,18 @@ import {
   readSync,
   closeSync,
 } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, resolve, relative, isAbsolute } from 'path';
 import { randomBytes } from 'crypto';
 import { spawnSync } from 'child_process';
 
-export const ACTIVE_MS = 60 * 1000;
+export const ACTIVE_MS = 180 * 1000;
 export const IDLE_MS = 30 * 60 * 1000;
 export const STALE_MS = 24 * 60 * 60 * 1000;
 export const COLLISION_WINDOW_MS = 5 * 60 * 1000;
 
 export const TOUCHES_ROTATE_THRESHOLD = 1000;
 export const TOUCHES_TAIL_LINES = 200;
-export const FILES_TOUCHED_CAP = 50;
+export const FILES_TOUCHED_CAP = 200;
 
 export interface SessionRecord {
   sessionId: string;
@@ -238,7 +244,9 @@ export function tailFileTouches(stateDir: string, lines = TOUCHES_TAIL_LINES): F
   if (!existsSync(path)) return [];
   try {
     const size = statSync(path).size;
-    const readBytes = Math.min(size, 64 * 1024);
+    // 512KB tail comfortably holds ≳1000 touch records; collision decisions read
+    // up to 1000 lines (see callers), so the byte window must not truncate them.
+    const readBytes = Math.min(size, 512 * 1024);
     const fd = openSync(path, 'r');
     const buf = Buffer.alloc(readBytes);
     readSync(fd, buf, 0, readBytes, size - readBytes);
@@ -361,11 +369,19 @@ export function classifyAge(ageMsec: number): 'active' | 'idle' | 'stale' {
 export function extractTargetFiles(toolName: string, toolInput: any, projectDir: string): string[] {
   if (!toolInput || typeof toolInput !== 'object') return [];
   const out: string[] = [];
+  // Normalize every path to the SAME shape `git status --porcelain` emits:
+  // forward-slash, relative to the project (≈ repo) root. Tools may hand us an
+  // absolute path, a path relative to a subdirectory cwd, or already-relative.
+  // A mismatch here is the #1 cause of "I edited this file but scope.ts says it
+  // is NOT MINE" — the string simply fails to equal the git porcelain path.
   const push = (p: any) => {
     if (typeof p !== 'string' || !p) return;
-    let rel = p;
-    if (p.startsWith(projectDir + '/')) rel = p.slice(projectDir.length + 1);
-    out.push(rel);
+    const abs = isAbsolute(p) ? p : resolve(projectDir, p);
+    let rel = relative(projectDir, abs);
+    // Outside the project tree (rare): keep the original so we never crash; it
+    // simply will not match a git path, which is the correct, safe outcome.
+    if (!rel || rel.startsWith('..')) rel = p;
+    out.push(rel.split('\\').join('/'));
   };
   if (toolName === 'Edit' || toolName === 'Write') {
     push(toolInput.file_path || toolInput.path);

package/stacks/_shared/hooks/pre-tool-use.ts

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-// @sv-version: 1.0.0
+// @sv-version: 1.1.0
 /**
  * PreToolUse Hook — Multi-Instance Coordination
  *
  * Wired with matcher `Edit|Write|MultiEdit|NotebookEdit`. Reads the file-touches
  * log + active peer sessions and decides:
  *
- *  - BLOCK if a peer is currently ACTIVE (heartbeat < 60s) AND touched the same
+ *  - BLOCK if a peer is currently ACTIVE (heartbeat < 180s) AND touched the same
  *    file within the last 5 minutes. The reason explains how to recover.
  *  - WARN (approve + systemMessage) if a peer touched the file recently but is
- *    only IDLE (60s — 5min).
+ *    only IDLE (180s — 5min).
  *  - APPROVE silently otherwise.
  *
  * Hook input:
@@ -100,7 +100,7 @@ function evaluate(
       `  1. Run \`npx tsx .claude/hooks/peers.ts list\` to see who is active.\n` +
       `  2. Notify them: \`npx tsx .claude/hooks/peers.ts notify <id-prefix> "I need to edit <file>, can you commit/stash?"\`\n` +
       `  3. Wait for them to commit, then retry — or have them call \`peers.ts cleanup\` if you confirm they are no longer editing.\n` +
-      `  4. If you must override: re-run the same Edit after 60s of peer inactivity (their heartbeat will go IDLE and the hook will downgrade to a warning).`;
+      `  4. If you must override: re-run the same Edit after 180s of peer inactivity (their heartbeat will go IDLE and the hook will downgrade to a warning).`;
     return { block: true, reason };
   }
 
@@ -141,7 +141,8 @@ async function main(): Promise<void> {
   }
 
   const peers = listPeerSessions(stateDir, sessionId || null);
-  const touches = tailFileTouches(stateDir);
+  // Read a wide tail so a peer's collision touch is not missed under heavy load.
+  const touches = tailFileTouches(stateDir, 1000);
 
   const verdict = evaluate(targetFiles, peers, touches, sessionId || '');