start-vibing-stacks 2.25.2 → 2.28.0

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

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

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

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

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

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

package/stacks/_shared/skills/multi-instance-coordination/SKILL.md

@@ -23,8 +23,8 @@ Every hook updates `lastSeenAt` (heartbeat). Thresholds:
 
 | Age of last activity | State    | Effect                                                                 |
 | -------------------- | -------- | ---------------------------------------------------------------------- |
-| < 60s                | active   | Counts for collision detection; PreToolUse may BLOCK Edit/Write.       |
-| 60s – 30min          | idle     | Surfaced as a warning; edits NOT blocked.                              |
+| < 180s               | active   | Counts for collision detection; PreToolUse may BLOCK Edit/Write.       |
+| 180s – 30min         | idle     | Surfaced as a warning; edits NOT blocked.                              |
 | > 30min              | stale    | Auto-archived on the next sweep.                                       |
 | > 24h                | removed  | Deleted entirely.                                                      |
 
@@ -40,12 +40,12 @@ Every hook updates `lastSeenAt` (heartbeat). Thresholds:
 
 | Peer who touched the same file last | Peer's heartbeat | Touch age | Decision |
 | ----------------------------------- | ---------------- | --------- | --------------------------------------------- |
-| any                                 | active (<60s)    | < 5min    | **BLOCK** with a recovery hint                |
-| any                                 | idle (60s–30min) | < 5min    | APPROVE + warning in `systemMessage`          |
+| any                                 | active (<180s)   | < 5min    | **BLOCK** with a recovery hint                |
+| any                                 | idle (180s–30min)| < 5min    | APPROVE + warning in `systemMessage`          |
 | any                                 | stale or gone    | any       | APPROVE silently                              |
 | no peer touched the file            | n/a              | n/a       | APPROVE silently                              |
 
-Override path: wait until the active peer's heartbeat goes idle (60s of no activity), then retry — the hook will downgrade to a warning. If the user explicitly tells you to override, ask them to run `peers notify <id> "I'm taking over <file>"` first so the other instance gets the heads-up.
+Override path: wait until the active peer's heartbeat goes idle (180s of no activity), then retry — the hook will downgrade to a warning. If the user explicitly tells you to override, ask them to run `peers notify <id> "I'm taking over <file>"` first so the other instance gets the heads-up.
 
 ## Talking to a peer
 

package/templates/CLAUDE-default.md

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

package/templates/CLAUDE-nodejs.md

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

package/templates/CLAUDE-php.md

@@ -2,11 +2,15 @@
 
 > **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
 
-## Last Change
+## Recent Changes
 
-**Branch:** main
-**Date:** {{DATE}}
-**Summary:** Initial project setup with start-vibing-stacks (PHP — API-first React SPA)
+<!-- APPEND-ONLY LIFO. Each Claude instance PREPENDS a new `### YYYY-MM-DD · branch · vX.Y.Z` heading
+     + 1-4 lines below it. Drop only the OLDEST entry when count > 10. NEVER edit a peer's entry.
+     `domain-updater` v3.0.0+ does this automatically post-commit.
+     Compactor (`claude-md-compactor.md §5-§6`) enforces the cap, not the prepend. -->
+
+### {{DATE}} · main · v0.1.0
+Initial project setup with start-vibing-stacks (PHP — API-first React SPA).
 
 ## 30 Seconds Overview
 
@@ -141,17 +145,17 @@ project/
 
 | Change Type | Sections to Update |
 |-------------|-------------------|
-| Any file change | Last Change (branch, date, summary) |
+| Any file change | PREPEND new entry to `## Recent Changes` (heading: `### YYYY-MM-DD · branch · vX.Y.Z` + 1-4 lines) |
 | API/routes | Critical Rules, Architecture |
 | New feature | 30s Overview, Architecture |
 | New gotcha | FORBIDDEN or NRY |
 | New dependency | Stack |
 | Workflow change | Workflow section |
 
-1. **Last Change** documents WHAT was done
-2. **Other sections** document HOW things work NOW
-3. **Both must be current** — updating only Last Change is insufficient
-4. Keep only the LATEST Last Change entry (no stacking)
+1. **`## Recent Changes`** documents WHAT was done across recent sessions (append-only LIFO, cap 10).
+2. **Other sections** document HOW things work NOW.
+3. **Both must be current** — prepending to Recent Changes is insufficient if rule sections went stale.
+4. **APPEND-ONLY** — PREPEND your entry below the HTML comment anchor; drop only the OLDEST entry when count > 10. NEVER edit a peer's entry, NEVER collapse two entries into one. Multi-instance safe by construction.
 
 ## Critical Rules
 
@@ -372,7 +376,7 @@ $results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 3. IMPLEMENT      → Bottom-up: FormRequest+Policy → Service → Resource → Controller → Route → React page
 4. TEST           → PHPUnit feature tests (happy + 401 + 403 + 422); React: api.test.ts
 5. DOCUMENT       → documenter agent for modified files; update domain docs
-6. UPDATE         → Update THIS FILE (CLAUDE.md) — Last Change + relevant sections
+6. UPDATE         → Update THIS FILE (CLAUDE.md) — PREPEND entry to ## Recent Changes (LIFO) + refresh relevant rule sections
 7. QUALITY        → PHPStan + PHPUnit + PHP-CS-Fixer + tsc + eslint
 8. COMMIT         → Conventional commits; merge to main
 ```

package/templates/CLAUDE-python.md

@@ -2,11 +2,15 @@
 
 > **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
 
-## Last Change
+## Recent Changes
 
-**Branch:** main
-**Date:** {{DATE}}
-**Summary:** Initial project setup with start-vibing-stacks (Python)
+<!-- APPEND-ONLY LIFO. Each Claude instance PREPENDS a new `### YYYY-MM-DD · branch · vX.Y.Z` heading
+     + 1-4 lines below it. Drop only the OLDEST entry when count > 10. NEVER edit a peer's entry.
+     `domain-updater` v3.0.0+ does this automatically post-commit.
+     Compactor (`claude-md-compactor.md §5-§6`) enforces the cap, not the prepend. -->
+
+### {{DATE}} · main · v0.1.0
+Initial project setup with start-vibing-stacks (Python).
 
 ## 30 Seconds Overview
 
@@ -213,22 +217,31 @@ pytest --tb=short         # Tests (MUST pass)
 
 | Change Type | What to Update |
 |-------------|----------------|
-| Any file change | Last Change section |
+| Any file change | PREPEND new entry to `## Recent Changes` (LIFO, cap 10) |
 | New feature | 30s Overview, Architecture if needed |
 | New pattern | Add to relevant section |
 | Gotcha discovered | Add to FORBIDDEN or NRY |
 | New dependency | Update Stack table |
 
-### Last Change Format (MANDATORY)
+### Recent Changes Format (MANDATORY)
+
+Each new entry is a `###` block PREPENDED below the HTML comment anchor. Multi-instance safe by construction (append-only LIFO, cap 10).
 
 ```markdown
-## Last Change
+## Recent Changes
+
+<!-- APPEND-ONLY LIFO ... (HTML comment, do NOT edit) -->
 
-**Branch:** feature/example
-**Date:** YYYY-MM-DD
-**Summary:** 1-2 sentences describing WHAT and WHY.
+### YYYY-MM-DD · feature/example · v0.2.0
+1-4 plain-text lines describing WHAT and WHY. Inline `code` allowed for agent/skill/file names.
+No bullets, no nested headers, no horizontal rules.
+
+### YYYY-MM-DD · main · v0.1.0
+(previous entry below — never edit a peer's entry)
 ```
 
+`domain-updater` v3.0.0+ does the prepend automatically post-commit. Drop only the OLDEST `### ` block when count exceeds 10. NEVER reorder middle entries; NEVER collapse two entries into one.
+
 ## Agent System
 
 | Agent | Purpose |