start-vibing-stacks 2.31.0 → 2.33.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.33.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/docker-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docker-patterns
-version: 2.0.0
+version: 2.1.0
 description: "Docker patterns for 2026: BuildKit + Buildx Bake (default builder for Docker Compose since June 2025), multi-stage builds, distroless / chiseled bases (90% size reduction, no shell), non-root users, .dockerignore, healthchecks, additional_contexts for service deps, secrets via build mounts (not COPY), reproducible builds. Stack examples: Node 22, Python 3.13 (uv), PHP 8.4 (FPM + Nginx)."
 ---
 
@@ -86,7 +86,16 @@ RUN apk add --no-cache libzip-dev oniguruma-dev icu-dev \
  && rm -rf /var/cache/apk/*
 WORKDIR /var/www/html
 COPY --from=vendor /app/vendor ./vendor
-COPY --chown=www-data:www-data . .
+# Only copy what the runtime actually needs (never .env, tests, .git, node_modules, etc.)
+COPY --chown=www-data:www-data artisan composer.json composer.lock ./
+COPY --chown=www-data:www-data app/ ./app/
+COPY --chown=www-data:www-data bootstrap/ ./bootstrap/
+COPY --chown=www-data:www-data config/ ./config/
+COPY --chown=www-data:www-data database/ ./database/
+COPY --chown=www-data:www-data public/ ./public/
+COPY --chown=www-data:www-data resources/ ./resources/
+COPY --chown=www-data:www-data routes/ ./routes/
+COPY --chown=www-data:www-data storage/ ./storage/
 USER www-data
 EXPOSE 9000
 HEALTHCHECK --interval=30s --timeout=3s CMD php-fpm-healthcheck || exit 1
@@ -203,3 +212,4 @@ For Kubernetes the Dockerfile HEALTHCHECK is informational only — the cluster
 - `security-baseline` (2025-A03) — supply chain: pin actions by SHA, sign images (Sigstore/cosign)
 - `observability` — `/healthz` + `/readyz` semantics
 - `ci-pipelines` — building & pushing in CI
+- `podman-patterns` — rootless execution, Quadlet, `podman play kube`, and daemonless alternative (same Dockerfiles work)