start-vibing-stacks 2.31.0 → 2.32.0

package/dist/index.js

@@ -34,6 +34,7 @@ const FLAGS = {
     version: args.includes('--version') || args.includes('-v'),
     apply: args.includes('--apply'),
     forceHooks: args.includes('--force-hooks') || args.includes('--force-legacy'),
+    withMemoryOptimization: args.includes('--with-memory-optimization'),
 };
 if (FLAGS.version) {
     console.log(PKG_VERSION);
@@ -59,6 +60,8 @@ if (FLAGS.help) {
     --no-claude       Skip Claude Code installation
     --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation
+    --with-memory-optimization
+                      Install the Memory Optimization Pipeline (MOP) for static memory maintenance
     --help, -h        Show this help
     --version, -v     Show version
 
@@ -350,6 +353,7 @@ async function main() {
     const setupOk = await setupProject(projectDir, config, {
         force: FLAGS.force,
         noClaude: FLAGS.noClaude,
+        withMemoryOptimization: FLAGS.withMemoryOptimization,
     });
     if (!setupOk) {
         ui.error('Setup failed.');

package/dist/setup.d.ts

@@ -14,4 +14,5 @@ export declare function loadStackConfig(stackId: string): StackConfig | null;
 export declare function setupProject(projectDir: string, config: ProjectConfig, options?: {
     force?: boolean;
     noClaude?: boolean;
+    withMemoryOptimization?: boolean;
 }): Promise<boolean>;

package/dist/setup.js

@@ -231,6 +231,13 @@ export async function setupProject(projectDir, config, options = {}) {
         if (existsSync(sharedMemoriesDir)) {
             copyDirRecursive(sharedMemoriesDir, join(claudeDir, 'memories'), options.force);
         }
+        // 12c. Copy Memory Optimization Pipeline (MOP) if flag is present
+        if (options.withMemoryOptimization) {
+            const sharedMopDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'memory-optimization');
+            if (existsSync(sharedMopDir)) {
+                copyDirRecursive(sharedMopDir, join(claudeDir, 'memory-optimization'), options.force);
+            }
+        }
         // 13. Write settings.json for Claude Code (complete config)
         const settings = {
             model: 'sonnet',

package/package.json

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

package/stacks/_shared/ads-agents/references/memory-optimization-rules.md

@@ -0,0 +1,29 @@
+# Memory Optimization Pipeline Rules
+
+> **Status:** Auto-loaded memory via `memory-optimization.md`.
+
+---
+
+## When to Suggest MOP
+
+The agent should suggest running the Memory Optimization Pipeline when any of the following objective signals are detected:
+
+- 3 or more redundant chunks across different memory files
+- 5 or more generic chunks (low specificity)
+- `CLAUDE.md` exceeding 35,000 characters
+- A static memory not updated for more than 30 days
+- Repeated "forgetting" of decisions or patterns during a session
+
+## How to Suggest
+
+Always suggest, never execute automatically:
+
+> "I detected X redundant/generic chunks in the memories. I recommend running:
+> `npx start-vibing-stacks memory optimize --dry-run`"
+
+## Safety Rules
+
+- Never propose modifying original `.md` files directly.
+- Always recommend reviewing the generated report first.
+- GEPA mode should only be suggested for very large or long-lived projects.
+- The MOP is a maintenance tool, not an autonomous agent.

package/stacks/_shared/memories/memory-optimization.md

@@ -0,0 +1,54 @@
+# Memory: Memory Optimization Pipeline (MOP)
+
+> **CARREGAR SEMPRE** — Esta memória explica o sistema de otimização de memórias estáticas do projeto. O agente deve entender que o MOP é uma ferramenta de manutenção segura, versionável e não intrusiva.
+
+---
+
+## O que é o MOP
+
+O Memory Optimization Pipeline (MOP) é uma ferramenta que avalia, densifica e evolui as memórias estáticas do projeto (`.claude/memories/*.md`) usando **LLM-as-Judge** e, opcionalmente, técnicas evolutivas (GEPA).
+
+**Princípio fundamental:** O MOP **nunca modifica** os arquivos originais. Ele sempre gera versões otimizadas (`.optimized.md`) e relatórios de mudanças para revisão humana.
+
+---
+
+## Regras de Ouro do MOP
+
+1. **Nunca modificar** arquivos `.md` originais
+2. **Nunca modificar** `CLAUDE.md`
+3. **Nunca modificar** Skills (`SKILL.md`)
+4. **Nunca adicionar** hooks automáticos no `settings.json`
+5. **Nunca rodar** automaticamente sem confirmação explícita do usuário
+6. **Sempre gerar** relatório explicativo antes de qualquer mudança
+7. **Sempre ser** idempotente e reversível
+
+---
+
+## Quando o MOP Deve Ser Invocado
+
+O agente deve sugerir o uso do MOP quando detectar:
+
+- 3 ou mais chunks redundantes entre memórias diferentes
+- 5 ou mais chunks genéricos (pouca especificidade)
+- `CLAUDE.md` com mais de 35.000 caracteres
+- Memória estática não atualizada há mais de 30 dias
+- Sinais de degradação de qualidade de memória (perda de decisões, padrões ou gotchas)
+
+**Nunca execute o MOP automaticamente.** Sempre sugira ou peça confirmação explícita (`npx start-vibing-stacks memory optimize --apply`).
+
+---
+
+## Integração com o Agente
+
+Quando o usuário pedir para otimizar memórias, o agente deve:
+
+1. Executar o pipeline em modo dry-run primeiro
+2. Apresentar o relatório gerado
+3. Só aplicar mudanças após confirmação explícita
+4. Nunca sobrescrever memórias originais sem criar backup explícito
+
+---
+
+## Lembrete para o Modelo
+
+O MOP existe para combater a **degradação progressiva** de memórias estáticas em projetos longos. Ele é uma ferramenta de **manutenção**, não um processo autônomo. Respeite rigorosamente as regras de não intrusão.

package/stacks/_shared/memory-optimization/chunker.ts

@@ -0,0 +1,53 @@
+import { randomUUID } from 'crypto';
+
+export interface MemoryChunk {
+  id: string;
+  text: string;
+  sourceFile: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+/**
+ * Semantic chunker (placeholder).
+ * In a real implementation, this would use LLM to split memories into
+ * semantically coherent chunks instead of naive line-based splitting.
+ */
+export function chunkMemory(content: string, sourceFile: string): MemoryChunk[] {
+  const lines = content.split('\n');
+  const chunks: MemoryChunk[] = [];
+  let currentChunk: string[] = [];
+  let startLine = 1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    currentChunk.push(line);
+
+    // Naive heuristic: split on double newlines or section headers
+    if (line.trim() === '' || line.startsWith('##')) {
+      if (currentChunk.length > 3) {
+        chunks.push({
+          id: randomUUID(),
+          text: currentChunk.join('\n').trim(),
+          sourceFile,
+          startLine,
+          endLine: i + 1
+        });
+        currentChunk = [];
+        startLine = i + 2;
+      }
+    }
+  }
+
+  if (currentChunk.length > 3) {
+    chunks.push({
+      id: randomUUID(),
+      text: currentChunk.join('\n').trim(),
+      sourceFile,
+      startLine,
+      endLine: lines.length
+    });
+  }
+
+  return chunks;
+}

package/stacks/_shared/memory-optimization/config.default.json

@@ -0,0 +1,29 @@
+{
+  "model": "sonnet",
+  "temperature": 0.3,
+  "maxTokensPerCall": 4000,
+  "criteria": {
+    "relevance": 0.30,
+    "specificity": 0.25,
+    "actionability": 0.20,
+    "uniqueness": 0.15,
+    "freshness": 0.10
+  },
+  "thresholds": {
+    "minScore": 0.60,
+    "mergeThreshold": 0.85,
+    "archiveThreshold": 0.40
+  },
+  "evolutionary": {
+    "enabled": false,
+    "generations": 5,
+    "populationSize": 20,
+    "elitismRate": 0.20,
+    "crossoverRate": 0.60,
+    "mutationRate": 0.20
+  },
+  "limits": {
+    "maxChunksPerMemory": 200,
+    "maxReportLength": 3000
+  }
+}

package/stacks/_shared/memory-optimization/evolutionary.ts

@@ -0,0 +1,14 @@
+/**
+ * Evolutionary (GEPA) layer (stub).
+ *
+ * This file exists for future expansion.
+ * GEPA is disabled by default in config.json.
+ * When enabled, this module would implement:
+ * - Population management
+ * - Crossover / Mutation operators
+ * - Fitness selection over generations
+ */
+export function runGEPA(chunks: any[], config: any): any[] {
+  console.log('[GEPA] Evolutionary optimization is disabled by default.');
+  return chunks;
+}

package/stacks/_shared/memory-optimization/judge.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+export interface ChunkEvaluation {
+  chunkId: string;
+  text: string;
+  scores: {
+    relevance: number;
+    specificity: number;
+    actionability: number;
+    uniqueness: number;
+    freshness: number;
+  };
+  finalScore: number;
+  recommendation: 'keep' | 'merge' | 'archive' | 'rewrite';
+  reason: string;
+}
+
+export interface JudgeConfig {
+  model: string;
+  temperature: number;
+  criteria: Record<string, number>;
+  thresholds: {
+    minScore: number;
+    mergeThreshold: number;
+    archiveThreshold: number;
+  };
+}
+
+const DEFAULT_CRITERIA = {
+  relevance: 0.30,
+  specificity: 0.25,
+  actionability: 0.20,
+  uniqueness: 0.15,
+  freshness: 0.10
+};
+
+export async function evaluateChunk(
+  chunk: { id: string; text: string },
+  config: JudgeConfig,
+  context: string
+): Promise<ChunkEvaluation> {
+  const prompt = buildJudgePrompt(chunk.text, config.criteria, context);
+
+  // In a real implementation, this would call the Claude API
+  // For now, we return a placeholder structure.
+  // The actual LLM call will be implemented when integrating with the pipeline.
+
+  const mockScores = {
+    relevance: 0.85,
+    specificity: 0.70,
+    actionability: 0.65,
+    uniqueness: 0.80,
+    freshness: 0.90
+  };
+
+  const finalScore = Object.entries(mockScores).reduce((acc, [key, value]) => {
+    return acc + value * (config.criteria[key as keyof typeof config.criteria] || 0);
+  }, 0);
+
+  let recommendation: ChunkEvaluation['recommendation'] = 'keep';
+  if (finalScore < config.thresholds.archiveThreshold) recommendation = 'archive';
+  else if (finalScore < config.thresholds.minScore) recommendation = 'rewrite';
+  else if (finalScore > config.thresholds.mergeThreshold) recommendation = 'merge';
+
+  return {
+    chunkId: chunk.id,
+    text: chunk.text,
+    scores: mockScores,
+    finalScore: Math.round(finalScore * 100) / 100,
+    recommendation,
+    reason: `Score ${finalScore.toFixed(2)} — ${recommendation} based on weighted criteria.`
+  };
+}
+
+function buildJudgePrompt(text: string, criteria: Record<string, number>, context: string): string {
+  return `You are an expert memory curator for AI coding agents.
+
+Evaluate the following memory chunk according to these weighted criteria:
+
+${Object.entries(criteria).map(([k, v]) => `- ${k}: ${v * 100}%`).join('\n')}
+
+Context about the project:
+${context}
+
+Chunk to evaluate:
+"""
+${text}
+"""
+
+Respond ONLY with a valid JSON object:
+{
+  "relevance": 0.0-1.0,
+  "specificity": 0.0-1.0,
+  "actionability": 0.0-1.0,
+  "uniqueness": 0.0-1.0,
+  "freshness": 0.0-1.0,
+  "recommendation": "keep" | "merge" | "archive" | "rewrite",
+  "reason": "one sentence justification"
+}`;
+}

package/stacks/_shared/memory-optimization/merger.ts

@@ -0,0 +1,17 @@
+import { MemoryChunk } from './chunker.js';
+
+export interface MergeSuggestion {
+  sourceChunks: string[];
+  mergedText: string;
+  reason: string;
+}
+
+/**
+ * Merger (placeholder).
+ * In a real implementation, this would use LLM to intelligently merge
+ * related chunks while preserving specificity and actionability.
+ */
+export function suggestMerges(chunks: MemoryChunk[]): MergeSuggestion[] {
+  // Placeholder: In real version, call LLM to find merge candidates
+  return [];
+}

package/stacks/_shared/memory-optimization/pipeline.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Memory Optimization Pipeline (MOP)
+ *
+ * Usage:
+ *   npx tsx .claude/memory-optimization/pipeline.ts optimize --dry-run
+ *   npx tsx .claude/memory-optimization/pipeline.ts optimize --apply
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { evaluateChunk, type JudgeConfig } from './judge.js';
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const MEMORIES_DIR = join(PROJECT_DIR, '.claude', 'memories');
+const MOP_DIR = join(PROJECT_DIR, '.claude', 'memory-optimization');
+const CONFIG_PATH = join(MOP_DIR, 'config.json');
+
+interface PipelineOptions {
+  dryRun: boolean;
+  apply: boolean;
+  gepa: boolean;
+}
+
+function loadConfig(): JudgeConfig {
+  if (existsSync(CONFIG_PATH)) {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  }
+  // Fallback to default
+  return JSON.parse(
+    readFileSync(join(dirname(import.meta.url), 'config.default.json'), 'utf8')
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command !== 'optimize') {
+    console.log('Usage: pipeline.ts optimize [--dry-run] [--apply] [--gepa]');
+    process.exit(1);
+  }
+
+  const options: PipelineOptions = {
+    dryRun: args.includes('--dry-run'),
+    apply: args.includes('--apply'),
+    gepa: args.includes('--gepa')
+  };
+
+  const config = loadConfig();
+
+  console.log('Memory Optimization Pipeline');
+  console.log(`Mode: ${options.dryRun ? 'DRY-RUN' : options.apply ? 'APPLY' : 'REPORT'}`);
+  console.log(`GEPA: ${options.gepa ? 'ENABLED' : 'DISABLED'}`);
+
+  // Placeholder for actual logic
+  // 1. Load memories
+  // 2. Chunk
+  // 3. Judge
+  // 4. (Optional) GEPA
+  // 5. Generate report + optimized files
+
+  console.log('\n[INFO] Pipeline skeleton executed. Full implementation pending.');
+  console.log('This is a safe dry-run placeholder. No files were modified.');
+}
+
+main().catch(err => {
+  console.error('Pipeline failed:', err);
+  process.exit(1);
+});

package/stacks/_shared/memory-optimization/templates/optimized.md.hbs

@@ -0,0 +1,12 @@
+# {{memoryName}} (Optimized)
+
+> **This is an optimized version generated by MOP.**  
+> Original file: `{{originalFile}}`  
+> Generated on: {{date}}
+
+---
+
+{{optimizedContent}}
+
+---
+*End of optimized memory. Review before replacing the original.*

package/stacks/_shared/memory-optimization/templates/report.md.hbs

@@ -0,0 +1,33 @@
+# Memory Optimization Report
+
+**Generated:** {{date}}
+**Mode:** {{mode}}
+**Memories analyzed:** {{memoryCount}}
+
+## Summary
+
+- Total chunks evaluated: {{totalChunks}}
+- Recommended to keep: {{keepCount}}
+- Recommended to merge: {{mergeCount}}
+- Recommended to archive: {{archiveCount}}
+- Recommended to rewrite: {{rewriteCount}}
+
+## Detailed Findings
+
+{{#each findings}}
+### {{sourceFile}}
+
+- **Recommendation:** {{recommendation}}
+- **Score:** {{score}}
+- **Reason:** {{reason}}
+
+{{/each}}
+
+## Recommended Actions
+
+1. Review the generated `.optimized.md` files.
+2. Run with `--apply` only after manual review.
+3. Commit the `.optimized.md` files for traceability.
+
+---
+*This report was generated by the Memory Optimization Pipeline (MOP). No original files were modified.*

package/stacks/_shared/skills/secrets-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: secrets-management
-version: 2.0.0
+version: 2.1.0
 description: "Environment variable hygiene, OIDC federation for CI/CD (2026 default — replaces long-lived static secrets), secret detection (gitleaks 3-layer: pre-commit + CI + GitHub push protection), rotation, and secret-store patterns. Invoke whenever .env, secrets, API keys, env-var-reading code, or CI cloud-deploy credentials are touched."
 ---
 
@@ -59,6 +59,81 @@ OPENAI_API_KEY=sk-...
 
 ---
 
+## `.env.d/` Directory Pattern (Multi-Work / Multi-Session)
+
+For projects with multiple worktrees, parallel Claude sessions, or complex environment matrices, use the `.env.d/` directory pattern instead of a single `.env` file.
+
+### Recommended Layout
+```
+.env.d/
+  local/
+    01-app.env
+    10-db.env
+    20-auth.env
+    30-third-party.env
+  staging/
+    01-app.env
+    ...
+  production/
+    01-app.env
+    ...
+  shared/
+    99-common.env
+```
+
+### Rules
+- **Load order:** Files are sourced alphabetically (`01-` before `10-` before `99-`).
+- **Session isolation:** Each Claude session should only touch files inside its own worktree's `.env.d/local/`.
+- **Never commit real secrets:** Only commit `.env.d/*/ *.example` or `.env.d/*/.gitkeep`.
+- **JSON / PEM / SSH keys:** Place in `.env.d/local/secrets/` (gitignored) and reference via absolute path in the `.env` files.
+
+```bash
+# .env.d/local/30-secrets.env
+PRIVATE_KEY_PATH=/absolute/path/to/.env.d/local/secrets/service-account.json
+SSH_KEY_PATH=/absolute/path/to/.env.d/local/secrets/id_ed25519
+```
+
+### `.gitignore` for `.env.d/`
+```gitignore
+.env.d/
+!**/.gitkeep
+!**/*.example
+```
+
+---
+
+## Secret Files (JSON, PEM, SSH Keys) — Multi-Session Safe Handling
+
+When a secret must live in a file (service account JSON, SSH private key, certificate bundle, etc.):
+
+1. **Store in `.env.d/<env>/secrets/`** (never in repo root or `src/`).
+2. **Reference by absolute path** in the corresponding `.env.d/<env>/*.env` file.
+3. **Never read the file content into a variable** unless you immediately redact it from logs/memory.
+4. **Claude sessions must never cross worktree boundaries** — the `pre-tool-use.ts` hook already enforces this via `filesTouched` tracking.
+
+### Example (Node.js)
+```ts
+import { readFileSync } from 'fs';
+
+const serviceAccount = JSON.parse(
+  readFileSync(process.env['GOOGLE_APPLICATION_CREDENTIALS']!, 'utf8')
+);
+```
+
+### Example (Python)
+```python
+from pathlib import Path
+import json
+
+key_path = Path(os.environ["PRIVATE_KEY_PATH"])
+service_account = json.loads(key_path.read_text())
+```
+
+### Multi-Session Coordination Note
+The coordination layer (`_state.ts`, `pre-tool-use.ts`, `stop-validator.ts`) treats `.env.d/` files the same as any other file. If two sessions attempt to edit the same secret file within 5 minutes, the second session is blocked. This is intentional — secrets must be edited serially.
+
+---
+
 ## Reading Env Vars Safely
 
 ### Node.js / TypeScript
@@ -329,3 +404,16 @@ Lockfile rules:
 - `observability` — log redaction details
 - `ci-pipelines` — OIDC patterns + workflow permissions
 - Stack `api-security-*` — usage patterns
+- `memory-optimization` — when this skill grows beyond ~200 lines, run MOP to keep it actionable
+
+## Memory Optimization Trigger
+
+If this skill accumulates:
+- 3+ duplicate rotation playbooks across stacks
+- 5+ generic "rotate after leak" paragraphs
+- Repeated OIDC examples that differ only by cloud provider
+
+→ Suggest running:
+```bash
+npx start-vibing-stacks memory optimize --dry-run
+```