start-vibing-stacks 2.37.0 → 2.38.0

package/README.md

@@ -6,7 +6,7 @@ Multi-stack AI workflow for **Claude Code** & **Cursor**. One command installs a
 npx start-vibing-stacks
 ```
 
-> Latest: **v2.34.0** — Advertising optimization memory system (detector bypass, creative cloaking, bot evasion, landing page validation) + Memory Optimization Pipeline (MOP) with LLM-as-Judge, `--with-memory-optimization` flag, new skills (`kubernetes-patterns`, `react-server-components`, `laravel-octane-inertia`, `podman-patterns`), and security hardening in container examples.
+> Latest: **v2.38.0** — New `dead-code-hygiene` skill: remove unused legacy/inert code after replacements so leftover paths do not confuse later agent context. Workflow nudge in `user-prompt-submit` + `/feature`/`/fix`. Universal skills: **30**.
 
 ---
 
@@ -15,7 +15,7 @@ npx start-vibing-stacks
 | Layer | Count | Purpose |
 |---|---|---|
 | Agents | **7** universal | `research-web` (MCP-first) · `documenter` (memory layer) · `domain-updater` · `commit-manager` · `tester` · `claude-md-compactor` (compaction) · **`security-auditor` (VETO)** |
-| Skills | **26** shared + stack-specific + frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
+| Skills | **30** shared + stack-specific + frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
 | Hooks | `session-start` · `user-prompt-submit` · `pre-tool-use` · `post-tool-use` · `stop-validator` · `final-check` | Multi-instance coordination + git/docs/secrets/code-quality gates |
 | Commands | `/feature` · `/fix` · `/research` · `/validate` · `/peers` | Slash commands |
 | Workflows | `ci.yml` + `security.yml` per stack (audit · gitleaks · CodeQL · **Semgrep** · **Trivy** · **CycloneDX SBOM** · **dependency-review** · **OpenSSF Scorecard**) | Copied to `.github/workflows/` when target is empty |
@@ -35,13 +35,13 @@ npx start-vibing-stacks
 
 ## Skill matrix
 
-### Universal (29 — shared across stacks)
+### Universal (30 — shared across stacks)
 
 | Group | Skills |
 |---|---|
 | **Security** | `security-baseline` · `secrets-management` · `ai-llm-security` |
 | **Observability** | `observability` |
-| **Reliability** | `error-handling` · `database-migrations` · `tool-resilience` |
+| **Reliability** | `error-handling` · `database-migrations` · `tool-resilience` · `dead-code-hygiene` |
 | **A11y / UX** | `accessibility-wcag22` · `ui-ux-audit` |
 | **CI / Quality** | `ci-pipelines` · `quality-gate` · `final-check` · `git-workflow` |
 | **Infra** | `docker-patterns` · `podman-patterns` · `kubernetes-patterns` · `hook-development` · `multi-instance-coordination` |
@@ -207,16 +207,17 @@ This release includes a comprehensive set of permissive memories for legitimate
 1. BRANCH         feature/ | fix/ | refactor/ | test/
 2. RESEARCH       research-web (MCP-first; new features only)
 3. IMPLEMENT      stack rules + strict types + security
-4. TEST           tester (Vitest / pytest / PHPUnit / Playwright)
-5. SECURITY       security-auditor — VETO on CRITICAL/HIGH/MEDIUM findings
-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, 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
+4. HYGIENE        dead-code-hygiene — delete unused legacy/inert paths from this change
+5. TEST           tester (Vitest / pytest / PHPUnit / Playwright)
+6. SECURITY       security-auditor — VETO on CRITICAL/HIGH/MEDIUM findings
+7. QUALITY        quality-gate: typecheck → lint → test → build
+8. COMMIT         commit-manager — verifies gates, diff-driven message, push
+9. DOCUMENT       documenter — maps files/commits to domains, regenerates _index.json
+10. WISDOM        domain-updater — records session learnings, PREPENDS new entry to CLAUDE.md ## Recent Changes (append-only LIFO, cap 10, multi-instance safe)
+11. COMPACT       claude-md-compactor — triggers if CLAUDE.md > 20 KB
 ```
 
-Steps 5–6 cannot be skipped — `security-auditor` and `quality-gate` veto `commit-manager` on findings.
+Steps 6–7 cannot be skipped — `security-auditor` and `quality-gate` veto `commit-manager` on findings.
 
 ---
 

package/package.json

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

package/stacks/_shared/commands/feature.md

@@ -1,27 +1,28 @@
 ---
 name: feature
-description: Start a new feature with the full workflow (research → plan → implement → test → security → quality → commit → docs).
-version: 1.1.0
+description: Start a new feature with the full workflow (research → plan → implement → hygiene → test → security → quality → commit → docs).
+version: 1.2.0
 ---
 
 # /feature — Start New Feature
 
 Always read `.claude/config/active-project.json` first to know the active stack.
 
-Execute in order — do not skip steps. Steps 5–6 have **VETO power** over commit.
+Execute in order — do not skip steps. Steps 6–7 have **VETO power** over commit.
 
 | # | Step | Agent / Skill |
 |---|---|---|
 | 1 | **Research** (only for new tech / patterns) | `research-web` |
 | 2 | **Plan** — break into tasks, create TODO list | (you, in plan mode) |
 | 3 | **Implement** — follow stack patterns + strict types | (you) |
-| 4 | **Test** — unit + e2e | `tester` |
-| 5 | **Security** — adversarial audit | `security-auditor` (VETO) |
-| 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 + 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` |
+| 4 | **Dead-code hygiene** — delete unused legacy/inert paths from this change (no `// LEGACY` stubs) | `dead-code-hygiene` |
+| 5 | **Test** — unit + e2e | `tester` |
+| 6 | **Security** — adversarial audit | `security-auditor` (VETO) |
+| 7 | **Quality** — typecheck → lint → test → build | `quality-gate` |
+| 8 | **Commit** — gate-aware, diff-driven message | `commit-manager` |
+| 9 | **Map** — files + commits → domains | `documenter` |
+| 10 | **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.
+If `security-auditor` returns CRITICAL/HIGH/MEDIUM, fix before re-running step 6. Steps 9–10 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).
+**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 8, use `/commit-mine` (skip `/feature` from Step 8 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.1.0
+description: Fix a bug — reproduce, isolate, minimal fix, fix-induced dead-code hygiene, regression test, security check, commit, record wisdom.
+version: 1.2.0
 ---
 
 # /fix — Fix Bug
@@ -13,13 +13,14 @@ Always read `.claude/config/active-project.json` first.
 | 1 | **Reproduce** — read the error, reproduce locally, isolate the root cause (NOT the symptom) | (you) |
 | 2 | **Failing test first** — write a regression test that proves the bug | `tester` |
 | 3 | **Apply minimal fix** — do not refactor adjacent code in the same commit | (you) |
-| 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, 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 |
+| 4 | **Dead-code hygiene (scoped)** — delete only code made unreachable by *this* fix (old branch, shim, duplicate). Broad cleanup → separate `refactor:` commit | `dead-code-hygiene` |
+| 5 | **Verify** — re-run the regression test + the wider suite | `tester` |
+| 6 | **Security** — only if the bug touched auth / input / secrets / SSRF surface | `security-auditor` (VETO) |
+| 7 | **Quality gate** — typecheck → lint → test → build | `quality-gate` |
+| 8 | **Commit** — `fix(scope): <subject>`, diff-driven body, per-instance scoped staging | `commit-manager` v3.0.0 |
+| 9 | **Map** — files + commit → domain | `documenter` v3.0.0 |
+| 10 | **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.
+**Multi-instance note:** Step 8 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 8 (no chain auto-trigger), use `/commit-mine` instead.

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// @sv-version: 1.2.0
+// @sv-version: 1.3.0
 /**
  * UserPromptSubmit Hook — Start Vibing Stacks
  *
@@ -10,6 +10,8 @@
  *     peer messages reach the user before this turn runs, and warn if active
  *     peers exist.
  *
+ * v1.3.0: workflow adds dead-code hygiene step (skill `dead-code-hygiene`) between
+ * WORK and quality gates — remove inert legacy paths before commit.
  * 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.
@@ -161,11 +163,15 @@ async function main(): Promise<void> {
 
 2. WORK through each item sequentially.
 
-3. Run quality gates: ${qualityCmd}
+3. DEAD-CODE HYGIENE — after replacements/refactors, delete unused legacy/inert paths
+   in the same change (skill: dead-code-hygiene). Evidence via grep + typecheck/tests;
+   do not leave // LEGACY stubs. On /fix: only code made unreachable by this fix.
 
-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).
+4. Run quality gates: ${qualityCmd}
 
-5. UPDATE CLAUDE.md:
+5. 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).
+
+6. UPDATE CLAUDE.md:
    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.
@@ -173,7 +179,7 @@ async function main(): Promise<void> {
    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}`;
+7. Run stop-validator before finishing.${standardsContext}${peersBlock}`;
 
   console.log(JSON.stringify({ continue: true, systemMessage }));
   process.exit(0);

package/stacks/_shared/skills/dead-code-hygiene/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: dead-code-hygiene
+version: 1.0.0
+description: Remove unused legacy/inert code after replacements and refactors so leftover paths do not confuse later agent context. Invoke after you replace a module, dual-path, shim, or helper and before quality gates. Prefer evidence (grep + typecheck/tests) over guesswork; never delete public APIs without confirmation.
+---
+
+# Dead-Code Hygiene
+
+**Invoke after a replacement, migration, or refactor** that makes an old path unreachable — before quality gates and commit. Leftover inert code is read by the next session and steers agents the wrong way.
+
+> Prefer **delete in the same change** over “leave for later.” Commenting-out or `// LEGACY` stubs are still context pollution.
+
+---
+
+## Golden Rules
+
+1. **Same change, not a follow-up TODO.** When you introduce the new path, remove the old one in that edit set.
+2. **Evidence before delete.** Grep for callers/imports/route names; run typecheck/tests. No evidence → leave it and note uncertainty.
+3. **Scope tight on `/fix`.** Only remove code made unreachable by *this* fix (old branch, dead shim). Broad cleanup → separate `refactor:` commit.
+4. **When uncertain, do not delete.** Prefer a short `TODO(dead-code): verify callers` over a wrong deletion.
+5. **Update docs/domains** when a path you remove was documented.
+
+---
+
+## When to Invoke
+
+| Signal | Action |
+|---|---|
+| Replaced helper / module / page with a new one | Delete old file + update imports |
+| Dual path (`v1` + `v2`, feature-flag both always-on) | Collapse to the live path; remove dead branch |
+| Compatibility shim with zero remaining callers | Delete shim |
+| Copy-pasted “keep for rollback” block in same PR | Delete; git history is the rollback |
+| Unused import / export flagged by lint | Remove in the same pass |
+
+---
+
+## Verification Protocol (before delete)
+
+1. **Search references** — symbol name, file basename, route/component string (Inertia `component:`, Next route segment, Laravel route name).
+2. **Check dynamic uses** — string dispatch, `import()`, reflection, config maps, Blade/React name tables.
+3. **Run the stack gate** — typecheck / PHPStan / ruff after removal.
+4. **Run relevant tests** — at least the suite covering the changed surface.
+
+```bash
+# Node / TS — find remaining references (adjust pattern)
+rg -n "OldHelper|old-helper" --glob '!dist/**' --glob '!node_modules/**'
+
+# PHP
+rg -n "OldHelper|old_helper" app/ routes/ resources/ tests/
+
+# Python
+rg -n "old_helper|OldHelper" --glob '!**/__pycache__/**' --glob '!.venv/**'
+```
+
+Optional tooling (prefer over guesswork when installed):
+
+| Stack | Tool |
+|---|---|
+| Node/TS | ESLint `no-unused-vars` / `knip` / `ts-prune` |
+| PHP | PHPStan level 4+ (dead code / always-true) |
+| Python | Ruff `F401`/`F841`, `vulture` |
+
+---
+
+## Safe vs Unsafe Deletions
+
+| Safe (with evidence) | Unsafe — do NOT delete without confirmation |
+|---|---|
+| Unreferenced private helper in same package | Public package API / exported library surface |
+| Orphan page after route rewrite | Feature-flagged path still toggled in prod |
+| Dead import after move | Dynamic import / string-dispatch target |
+| Empty wrapper that only re-exports removed code | Test fixtures / factories used by name |
+| Commented-out blocks left from this session | Migration “down” paths still required |
+
+---
+
+## Anti-Patterns (FORBIDDEN)
+
+| Action | Why |
+|---|---|
+| Leave `// OLD:` / `# LEGACY` blocks “just in case” | Next agent reads them as live guidance |
+| Keep dual implementations indefinitely | Doubles maintenance + context noise |
+| Delete by filename alone without grep | Breaks dynamic / config references |
+| Broad cleanup inside a minimal `/fix` | Violates fix scope; mix bugs with refactors |
+| Suppress unused-lint instead of removing | Hides the signal |
+
+---
+
+## Polyglot Examples
+
+```ts
+// WRONG — new path + inert old export left for "rollback"
+export { NewCheckout } from './new-checkout';
+export { OldCheckout } from './old-checkout'; // unused; confuses next session
+
+// CORRECT — single live path
+export { NewCheckout } from './new-checkout';
+// delete old-checkout.ts after rg shows zero callers
+```
+
+```php
+// WRONG — route still points at unused controller after rewrite
+// Route::get('/billing', [OldBillingController::class, 'show']);
+
+// CORRECT — update route + delete OldBillingController once rg is clean
+Route::get('/billing', [BillingController::class, 'show']);
+```
+
+```python
+# WRONG — keep unused helper after extract
+def legacy_normalize(x):  # no callers
+    return x.strip()
+
+# CORRECT — delete legacy_normalize; keep only the live path
+def normalize(x: str) -> str:
+    return x.strip()
+```
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] Replaced paths: old files/exports removed or still have proven callers
+- [ ] No `LEGACY` / commented dual implementations added in this change
+- [ ] Grep clean for removed symbol names
+- [ ] Typecheck / lint / relevant tests pass
+- [ ] Domain docs / CLAUDE.md updated if a documented path was removed
+- [ ] `/fix` scope: only fix-induced dead code (else separate refactor commit)
+
+## See Also
+
+- `final-check` — mechanical leftovers (`console.log`, `any`, debug dumps); complementary
+- `quality-gate` — typecheck/lint/test/build after hygiene
+- `git-workflow` — use `refactor:` for broad dead-code deletions; keep `/fix` minimal
+- `tool-resilience` — if grep/edit tools fail while verifying callers
+- `error-handling` — application error paths (not inert-code cleanup)

package/stacks/_shared/skills/final-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: final-check
-version: 2.0.0
+version: 2.0.1
 description: Final validator with VETO power. Now executable — runs `npx tsx .claude/hooks/final-check.ts` to scan for debug statements, secrets, .skip, any, RCE risks, SQL concat. Blocks completion on CRITICAL/HIGH findings.
 ---
 
@@ -88,6 +88,7 @@ The default Stop is `stop-validator.ts` (git/branch/CLAUDE.md/secret scan). `fin
 
 ## See Also
 
+- `dead-code-hygiene` — remove unused legacy/inert paths after replacements (run before this scan)
 - `quality-gate` — typecheck/lint/test/build (different scope)
 - `security-baseline` — what the secret/RCE rules enforce
 - `stop-validator.ts` — git/branch/docs gate (sibling, complementary)

package/stacks/_shared/skills/quality-gate/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: quality-gate
-version: 1.0.0
+version: 1.0.1
+description: Run stack quality checks (typecheck → lint → test → build) before commit. Invoke after dead-code hygiene and before commit-manager. Blocks on required gate failures.
 ---
 
 # Quality Gate — Verification System
@@ -60,3 +61,9 @@ bun run build                              # Build verification (must come AFTER
 2. **FIX ERRORS, DON'T SKIP** — never use `--no-verify`
 3. **ORDER MATTERS** — run in defined order (cheapest first)
 4. **REPORT RESULTS** — show pass/fail for each gate
+
+## See Also
+
+- `dead-code-hygiene` — delete unused legacy/inert code after replacements (before this gate)
+- `final-check` — mechanical leftovers / secrets / RCE scan (complementary)
+- `git-workflow` — commit only after required gates pass

package/stacks/nodejs/stack.json

@@ -114,7 +114,8 @@
     "openapi-design",
     "docker-patterns",
     "podman-patterns",
-    "tool-resilience"
+    "tool-resilience",
+    "dead-code-hygiene"
   ],
   "requirements": [
     {

package/stacks/php/stack.json

@@ -104,7 +104,8 @@
     "openapi-design",
     "docker-patterns",
     "podman-patterns",
-    "tool-resilience"
+    "tool-resilience",
+    "dead-code-hygiene"
   ],
   "requirements": [
     {

package/stacks/python/stack.json

@@ -74,7 +74,8 @@
     "api-security-python",
     "docker-patterns",
     "podman-patterns",
-    "tool-resilience"
+    "tool-resilience",
+    "dead-code-hygiene"
   ],
   "requirements": [
     {