wogiflow 1.5.5 → 1.5.7

package/.claude/rules/README.md

@@ -0,0 +1,60 @@
+# Project Rules
+
+This directory contains coding rules and patterns for this project, organized by category.
+
+## Structure
+
+```
+.claude/rules/
+├── code-style/           # Naming conventions, formatting
+│   └── naming-conventions.md
+├── security/             # Security patterns and practices
+│   └── security-patterns.md
+├── architecture/         # Design decisions and patterns
+│   ├── component-reuse.md
+│   └── model-management.md
+└── README.md
+```
+
+## How Rules Work
+
+Rules are automatically loaded by Claude Code based on:
+- **alwaysApply: true** - Rule is always loaded
+- **alwaysApply: false** - Rule is loaded based on `globs` or `description` relevance
+- **globs** - File patterns that trigger rule loading
+
+## Adding New Rules
+
+1. Choose the appropriate category subdirectory
+2. Create a `.md` file with frontmatter:
+
+```yaml
+---
+alwaysApply: false
+description: "Brief description for relevance matching"
+globs: src/**/*.ts  # Optional: only load for these files
+---
+```
+
+3. Write the rule content in markdown
+
+## Categories
+
+| Category | Purpose |
+|----------|---------|
+| code-style | Naming conventions, formatting, file structure |
+| security | Security patterns, input validation, safe practices |
+| architecture | Design decisions, component patterns, system organization |
+
+## Auto-Generation
+
+Some rules can be auto-generated from `.workflow/state/decisions.md`:
+
+```bash
+node scripts/flow-rules-sync.js
+```
+
+The sync script will route rules to appropriate category subdirectories.
+
+---
+Last updated: 2026-01-12

package/.claude/rules/architecture/component-reuse.md

@@ -0,0 +1,38 @@
+---
+globs: src/components/**/*
+alwaysApply: false
+description: "Component reuse policy - always check app-map.md before creating components"
+---
+
+# Component Reuse Policy
+
+**Rule**: Always check `app-map.md` before creating any component.
+
+## Priority Order
+
+1. **Use existing** - Check if component already exists in app-map
+2. **Add variant** - Extend existing component with a new variant
+3. **Extend** - Create a wrapper/HOC around existing component
+4. **Create new** - Only as last resort
+
+## Before Creating Components
+
+```bash
+# Check app-map first
+cat .workflow/state/app-map.md | grep -i "button"
+
+# Or search codebase
+grep -r "Button" src/components/
+```
+
+## Variant vs New Component
+
+Prefer variants when:
+- Same base functionality, different appearance
+- Same HTML structure, different styling
+- Same component, different size/color/state
+
+Create new component when:
+- Fundamentally different functionality
+- Different DOM structure
+- Different state management

package/.claude/rules/architecture/document-structure.md

@@ -0,0 +1,76 @@
+---
+alwaysApply: true
+description: "All AI-context documents must use PIN markers for targeted context loading"
+---
+
+# Document Structure for AI Context
+
+All documents in `.workflow/` that are used as AI context MUST follow the PIN standard.
+
+## Required Structure
+
+### 1. Header with PIN List
+Every document starts with a comment listing all pins in the document:
+```markdown
+<!-- PINS: pin1, pin2, pin3 -->
+```
+
+### 2. Section PIN Markers
+Each major section has a PIN marker comment:
+```markdown
+### Section Title
+<!-- PIN: section-specific-pin -->
+[Content]
+```
+
+### 3. PIN Naming Convention
+- Use kebab-case: `user-authentication`, not `userAuthentication`
+- Use semantic names: `error-handling`, not `eh`
+- Use compound names for specificity: `json-parse-safety`
+
+## Why PINs Matter
+
+The PIN system enables:
+1. **Targeted context loading**: Only load sections relevant to current task
+2. **Cheaper model routing**: Haiku can fetch only relevant sections for Opus
+3. **Change detection**: Hash sections independently for smart invalidation
+4. **Cross-reference**: Link sections by PIN across documents
+
+## Example Document
+
+```markdown
+# Config Reference
+
+<!-- PINS: database, authentication, api-keys, environment -->
+
+## Database Settings
+<!-- PIN: database -->
+| Setting | Default | Description |
+|---------|---------|-------------|
+
+## Authentication
+<!-- PIN: authentication -->
+| Setting | Default | Description |
+|---------|---------|-------------|
+```
+
+## Parsing
+
+The PIN system automatically parses documents with:
+- `flow-section-index.js` - Generates section index with pins
+- `flow-section-resolver.js` - Resolves sections by PIN lookup
+- `getSectionsByPins(['auth', 'security'])` - Fetch only relevant sections
+
+## Files That Must Have PINs
+
+| File | Required PINs |
+|------|---------------|
+| `decisions.md` | Per coding rule/pattern |
+| `app-map.md` | Per component/screen |
+| `product.md` | Per product section |
+| `stack.md` | Per technology |
+
+## Validation
+
+Run `node scripts/flow-section-index.js --force` to regenerate the index.
+Check `.workflow/state/section-index.json` for indexed sections and their pins.

package/.claude/rules/architecture/feature-refactoring-cleanup.md

@@ -0,0 +1,87 @@
+---
+alwaysApply: false
+description: "Cleanup checklist when refactoring or renaming features"
+globs:
+  - "scripts/*.js"
+  - ".claude/skills/**/*"
+---
+
+# Feature Refactoring Cleanup
+
+When refactoring, renaming, or replacing a feature, ensure complete cleanup of the old implementation.
+
+## Mandatory Cleanup Checklist
+
+When a feature is refactored or renamed, you MUST:
+
+### 1. Remove Old Code
+- [ ] Delete old script files (e.g., `flow-old-feature.js`)
+- [ ] Remove old skill directories (e.g., `.claude/skills/old-feature/`)
+- [ ] Remove old hook files if applicable
+
+### 2. Update Configuration
+- [ ] Rename config keys (e.g., `oldFeature` → `newFeature`)
+- [ ] Remove from `skills.installed` array if skill was removed
+- [ ] Update any feature flags
+
+### 3. Update Documentation
+- [ ] Rename/update doc files in `.claude/docs/`
+- [ ] Update command references in `commands.md`
+- [ ] Update skill-matching.md if skill changed
+- [ ] Search for old name in all `.md` files
+
+### 4. Clean References
+- [ ] Search codebase: `grep -r "old-feature-name" .`
+- [ ] Update imports in dependent scripts
+- [ ] Update any hardcoded references
+
+### 5. Update State Files
+- [ ] Clean `.workflow/state/` of old state files
+- [ ] Update `ready.json` if tasks reference old feature
+- [ ] Archive old change specs
+
+## Search Commands
+
+Run these to find lingering references:
+
+```bash
+# Find all references to old feature
+grep -r "old-feature-name" --include="*.js" --include="*.md" --include="*.json" .
+
+# Find in config
+grep "oldFeatureName" .workflow/config.json
+
+# Find skill references
+grep -r "old-feature" .claude/
+```
+
+## Why This Matters
+
+Incomplete cleanup causes:
+- **Confusion**: Old commands/skills appear to work but don't
+- **Bloat**: Dead code accumulates
+- **Errors**: Old references cause runtime failures
+- **Documentation drift**: Docs describe non-existent features
+
+## Example: transcript-digestion → long-input-gate
+
+When this refactoring happened without proper cleanup:
+
+| Artifact | Status | Should Have Been |
+|----------|--------|------------------|
+| `.claude/skills/transcript-digestion/` | Left behind | Deleted |
+| `config.transcriptDigestion` | Left as-is | Renamed to `longInputGate` |
+| `skills.installed` array | Still listed | Removed |
+| `skill-matching.md` | Old references | Updated |
+| `transcript-digestion.md` doc | Still existed | Renamed/rewritten |
+
+## Automation Opportunity
+
+Consider adding a `flow refactor-cleanup <old-name> <new-name>` command that:
+1. Searches for all references
+2. Shows what needs updating
+3. Optionally auto-updates simple cases
+
+---
+
+Last updated: 2026-01-14

package/.claude/rules/architecture/model-management.md

@@ -0,0 +1,35 @@
+---
+globs: scripts/flow-model*.js
+alwaysApply: false
+description: "Model management architecture - two separate systems for different purposes"
+---
+
+# Model Management Architecture
+
+**Context**: Phase 1 introduced model registry and stats system alongside existing model-adapter.
+
+## Two Model Systems
+
+### 1. flow-model-adapter.js - Prompt Adaptation
+
+- `getCurrentModel()` returns normalized model name (string)
+- Focus: Per-model prompt adjustments, learning, and corrections
+- Imports: Used by flow-knowledge-router.js
+
+### 2. flow-models.js - Registry and Stats
+
+- `getCurrentModel()` returns `{name, info, source}` object
+- Focus: Model listing, routing recommendations, cost tracking
+- Standalone CLI commands: `flow models [subcommand]`
+
+## Design Decision
+
+**Keep them separate** because:
+- Different return types serve different consumers
+- Adapter system needs just the name for pattern matching
+- Registry system needs full model metadata for display/routing
+- Merging would create unnecessary coupling
+
+## Future Consideration
+
+Could extract shared model detection logic into a common utility if they drift apart, but avoid premature abstraction.

package/.claude/rules/architecture/self-maintenance.md

@@ -0,0 +1,87 @@
+---
+description: "Patterns for modifying WogiFlow itself (scripts, templates, config)"
+alwaysApply: false
+globs: "scripts/**,*.workflow/**,.claude/**,templates/**,agents/**,lib/**"
+---
+
+# WogiFlow Self-Maintenance Patterns
+
+When modifying WogiFlow's own code (scripts/, templates/, config, hooks), follow these patterns.
+
+## 1. Template-First Changes
+
+CLAUDE.md is **generated**, not hand-edited. Changes must go through the template system:
+
+```
+.workflow/templates/claude-md.hbs       # Main template
+.workflow/templates/partials/*.hbs      # Partial templates
+```
+
+After editing templates, regenerate:
+```bash
+node scripts/flow-bridge.js sync claude-code
+```
+
+**Never edit CLAUDE.md directly** - changes will be overwritten on next sync.
+
+## 2. Three-Layer Hook Architecture
+
+All hooks follow: Entry → Core → Adapter
+
+```
+scripts/hooks/entry/claude-code/<name>.js  # CLI-specific entry point
+scripts/hooks/core/<name>.js               # CLI-agnostic logic
+scripts/hooks/adapters/claude-code.js      # Transform results
+```
+
+When adding/modifying hooks:
+- Logic goes in `core/` (not entry)
+- Entry files only parse input and call core
+- Register hook in `.claude/settings.local.json`
+- Add config toggle in `.workflow/config.json` under `hooks.rules`
+
+## 3. Config Changes Need Documentation
+
+When adding config keys:
+- Use `_comment_<keyName>` for inline documentation of non-obvious settings
+- Update config.schema.json if it exists
+- Ensure `lib/installer.js` handles the new key for fresh installs
+
+## 4. State File Templates
+
+For files in `.workflow/state/` that target projects need:
+- Create both the file AND a `.template` version
+- Templates go in `.workflow/state/<name>.template` (for init/onboard)
+- Also add to `templates/` directory (for npm distribution)
+
+## 5. Slash Commands Are Flat Files
+
+Slash commands in `.claude/commands/` must be flat `.md` files:
+```
+.claude/commands/wogi-start.md     ← Correct (flat file)
+.claude/commands/wogi-start/       ← Wrong (directory)
+```
+
+## 6. Two Agent Directories
+
+| Directory | Purpose | Used By |
+|-----------|---------|---------|
+| `agents/` | 11 persona files | Health checks, CLI |
+| `.workflow/agents/` | Review checklists | wogi-review |
+
+Don't confuse them. `agents/security.md` (persona) is different from `.workflow/agents/security.md` (OWASP checklist).
+
+## 7. Regression Prevention
+
+When modifying flow-*.js scripts:
+- Run `node --check scripts/<file>.js` after edits
+- WogiFlow has no test suite - syntax checking is the safety net
+- Check for circular dependencies when moving shared functions
+
+## 8. Feature Refactoring Cleanup
+
+When renaming/replacing a feature, follow the full checklist in `.claude/rules/architecture/feature-refactoring-cleanup.md`. Key steps:
+- Remove old script files
+- Update config keys
+- Update documentation references
+- Search all `.md` files for old name

package/.claude/rules/code-style/naming-conventions.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: true
+description: "Naming conventions for files and code variants"
+---
+
+# Naming Conventions
+
+## File Names
+
+Use **kebab-case** for all file names in this project.
+
+Examples:
+- `flow-health.js` (correct)
+- `flowHealth.js` (incorrect)
+- `flow_health.js` (incorrect)
+
+## Variant Names
+
+Use consistent variant names for components:
+
+| Category | Values |
+|----------|--------|
+| Size | `sm`, `md`, `lg`, `xl` |
+| Intent | `primary`, `secondary`, `danger`, `success`, `warning` |
+| State | `default`, `hover`, `active`, `disabled` |
+
+Examples:
+```jsx
+<Button size="sm" intent="primary" />
+<Badge variant="warning" />
+```
+
+## Catch Block Variables
+
+Use `err` for all catch blocks in this codebase.
+
+**Avoid**: `e`, `error`, `ex`, `exception` - these cause confusion with loop variables.
+
+```javascript
+// Good
+try {
+  doSomething();
+} catch (err) {
+  console.error(err.message);
+}
+
+// Bad - 'e' conflicts with common iterator variables
+try {
+  items.map(e => e.value);  // 'e' used as iterator
+} catch (e) {
+  console.error(e.message);  // Easy to confuse with iterator 'e'
+}
+```
+
+**Reason**: Standardizing on `err` prevents mix-ups when `.map(e => ...)` is used nearby.

package/.claude/rules/security/security-patterns.md

@@ -0,0 +1,176 @@
+---
+alwaysApply: true
+description: "Security patterns for file operations, JSON parsing, and path handling"
+---
+
+# Security Patterns
+
+Critical security patterns for this project.
+
+## 1. File Read Safety
+
+Always wrap `fs.readFileSync()` in try-catch, even after `fileExists()` check.
+
+**Reason**: Race conditions, permission changes, symlink issues can still cause failures.
+
+```javascript
+// Good
+try {
+  const content = fs.readFileSync(path, 'utf-8');
+} catch (err) {
+  // Handle gracefully
+}
+
+// Bad - can still throw even if file existed
+if (fs.existsSync(path)) {
+  const content = fs.readFileSync(path, 'utf-8');
+}
+```
+
+## 2. JSON Parsing Safety
+
+Use `safeJsonParse()` from flow-utils.js instead of raw `JSON.parse()`.
+
+- Check for `__proto__`, `constructor`, `prototype` injection
+- Validate parsed structure has expected fields before use
+- Located in: `scripts/flow-utils.js`
+
+```javascript
+// Good
+const config = safeJsonParse(filePath, {});
+
+// Bad - vulnerable to prototype pollution
+const config = JSON.parse(fs.readFileSync(filePath));
+```
+
+## 3. Template Substitution Safety
+
+When implementing template substitution:
+- Block access to `__proto__`, `constructor`, `prototype` keys
+- Use `Object.prototype.hasOwnProperty.call()` for property access
+- Example: See `applyTemplate()` in flow-prompt-composer.js
+
+## 4. Path Safety
+
+- Validate patterns before `path.join()` with user/config data
+- Use `isPathWithinProject()` for defense-in-depth
+- Glob-to-regex: Use `[^/]*` not `.*` to prevent path separator matching
+
+```javascript
+// Good
+if (!isPathWithinProject(targetPath)) {
+  throw new Error('Path outside project');
+}
+
+// Bad - allows path traversal
+const fullPath = path.join(baseDir, userInput);
+```
+
+## 5. Module Dependencies
+
+- Check for circular dependencies when refactoring shared functions
+- Node.js handles circular deps but can cause undefined exports during load
+
+## 6. Claude Code Permission Patterns (2.1.7+)
+
+When configuring permission rules in Claude Code, avoid overly permissive wildcards.
+
+**Vulnerability fixed in 2.1.7**: Wildcard permission rules could match compound commands containing shell operators (`;`, `&&`, `||`, `|`).
+
+```javascript
+// DANGEROUS - could match "npm test && rm -rf /"
+"allow": "npm *"
+
+// SAFER - be specific about allowed commands
+"allow": "npm test"
+"allow": "npm run build"
+"allow": "npm install"
+
+// BEST - use semantic prompts instead of wildcards
+// In ExitPlanMode allowedPrompts:
+{ "tool": "Bash", "prompt": "run tests" }
+{ "tool": "Bash", "prompt": "install dependencies" }
+```
+
+**Best practices:**
+- Avoid `*` wildcards in permission rules
+- Use specific command patterns
+- Prefer semantic permission prompts over literal command matching
+- Never allow broad patterns like `rm *` or `git *`
+- Review permission rules after Claude Code updates
+
+## 7. Windows Path Safety
+
+On Windows, be aware of path-related issues:
+
+- Temp directory paths may contain characters like `\t` or `\n` that could be misinterpreted as escape sequences
+- Use raw strings or proper escaping when constructing paths
+- Cloud sync tools (OneDrive, Dropbox) and antivirus may touch file timestamps without changing content
+
+```javascript
+// Good - use path.join() which handles platform differences
+const tempPath = path.join(os.tmpdir(), 'myfile.txt');
+
+// Bad - manual concatenation can break on Windows
+const tempPath = os.tmpdir() + '/myfile.txt';
+```
+
+## 8. Shell Command Parameter Validation
+
+When executing shell commands with dynamic parameters, always validate inputs.
+
+**Risk**: Command injection via unvalidated parameters passed to execSync/spawn.
+
+```javascript
+// DANGEROUS - lang parameter not validated
+execSync(`sg --pattern "${pattern}" --lang ${lang} --json "${path}"`);
+
+// SAFER - validate against whitelist
+const ALLOWED_LANGUAGES = new Set(['typescript', 'javascript', 'python', 'go']);
+if (!ALLOWED_LANGUAGES.has(lang)) {
+  throw new Error(`Unsupported language: ${lang}`);
+}
+
+// BEST - use execFile with array arguments (no shell interpretation)
+const { execFileSync } = require('child_process');
+execFileSync('sg', ['--pattern', pattern, '--lang', lang, '--json', path]);
+```
+
+**Best practices:**
+- Validate all dynamic parameters against allowlists
+- Prefer `execFile`/`execFileSync` with array arguments over `exec`/`execSync` with template strings
+- When using template strings, escape all user-controlled values
+- Never interpolate user input directly into shell commands
+
+## 9. Temp Directory Isolation (Claude Code 2.1.23+)
+
+On shared systems (CI servers, multi-user machines), use per-user temp directories to prevent permission conflicts.
+
+**Fixed in Claude Code 2.1.23**: Per-user temp directory isolation prevents permission conflicts.
+
+```javascript
+// Good - per-user isolation
+const userId = process.getuid?.() ?? process.env.USER ?? process.env.USERNAME ?? 'default';
+const tempDir = path.join(os.tmpdir(), `myapp-${userId}`);
+
+// Bad - global temp path on shared systems
+const tempDir = path.join(os.tmpdir(), 'myapp');
+```
+
+**Best practices:**
+- Use UID on Unix systems (`process.getuid()`)
+- Fall back to username environment variables on Windows
+- Always provide a 'default' fallback for edge cases
+- This pattern is used in `flow-worktree.js` for worktree isolation
+
+## 10. Search/Grep Timeout Handling (Claude Code 2.1.23+)
+
+**Fixed in Claude Code 2.1.23**: Ripgrep search timeouts now report errors instead of silently returning empty results.
+
+**Impact on WogiFlow:** Component detection, auto-context loading, and pattern matching rely on search operations. Before 2.1.23, search timeouts could cause false negatives.
+
+**Best practices:**
+- Handle empty search results gracefully - they may indicate timeout
+- Add retry logic for search-dependent operations
+- Log warnings when searches return unexpectedly empty
+- Consider fallback strategies (glob-based search if grep fails)

package/.claude/settings.json

@@ -35,7 +35,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Edit|Write|TodoWrite|Skill|Bash",
+        "matcher": "Edit|Write|TodoWrite|Skill|Bash|EnterPlanMode",
         "hooks": [
           {
             "type": "command",
@@ -115,6 +115,6 @@
     ]
   },
   "_wogiFlowManaged": true,
-  "_wogiFlowVersion": "1.4.5",
+  "_wogiFlowVersion": "1.5.7",
   "_comment": "Shared WogiFlow hook configuration. Committed to repo for team use. User-specific overrides go in settings.local.json."
 }

package/.claude/skills/figma-analyzer/knowledge/learnings.md

@@ -0,0 +1,11 @@
+# Figma Analyzer Learnings
+
+Learnings captured from using the Figma Analyzer skill.
+
+---
+
+## Patterns Learned
+
+<!-- Learnings will be captured automatically during skill usage -->
+
+---

package/.workflow/agents/performance.md

@@ -0,0 +1,112 @@
+# Performance Review Agent
+
+Expert agent for identifying performance issues in code changes.
+
+## Role
+
+Detect performance anti-patterns, inefficient algorithms, and resource management issues.
+
+## Performance Checklist
+
+### Async & Concurrency
+- [ ] No sequential awaits that could be `Promise.all`
+- [ ] No blocking I/O in async contexts
+- [ ] No unhandled promise rejections
+- [ ] Async iterators used efficiently
+
+### Memory Management
+- [ ] Event listeners cleaned up (removeEventListener, unsubscribe)
+- [ ] Large objects released when no longer needed
+- [ ] No closures capturing unnecessary scope
+- [ ] Streams used for large data instead of loading into memory
+
+### Data Access Patterns
+- [ ] No N+1 query patterns (loop with individual DB/API calls)
+- [ ] Batch operations used where available
+- [ ] Results cached when accessed multiple times
+- [ ] Pagination used for large result sets
+
+### Bundle & Import Efficiency
+- [ ] No large library imports when small utility suffices
+- [ ] Dynamic imports for code-split boundaries
+- [ ] Tree-shakeable imports (named vs default)
+- [ ] No duplicate dependencies
+
+### Computation
+- [ ] No unnecessary re-computation (memoize expensive operations)
+- [ ] Appropriate data structures (Map/Set vs Array for lookups)
+- [ ] Early returns to avoid unnecessary work
+- [ ] No redundant iterations (filter+map that could be reduce)
+
+### React-Specific (skip if project does not use React — check package.json for "react" dependency)
+- [ ] Components memoized where appropriate (React.memo, useMemo, useCallback)
+- [ ] No inline object/array creation in render causing re-renders
+- [ ] Keys are stable and meaningful (not array index for dynamic lists)
+- [ ] useEffect dependencies are correct (no missing deps, no over-triggering)
+
+## Common Patterns to Flag
+
+```javascript
+// BAD: Sequential awaits (N+1 pattern)
+for (const id of ids) {
+  const result = await fetchItem(id);
+  results.push(result);
+}
+
+// GOOD: Parallel execution
+const results = await Promise.all(ids.map(id => fetchItem(id)));
+```
+
+```javascript
+// BAD: Event listener leak
+useEffect(() => {
+  window.addEventListener('resize', handler);
+  // Missing cleanup!
+}, []);
+
+// GOOD: Cleanup on unmount
+useEffect(() => {
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler);
+}, []);
+```
+
+```javascript
+// BAD: Large library for small task
+import _ from 'lodash';
+const unique = _.uniq(items);
+
+// GOOD: Use native or targeted import
+const unique = [...new Set(items)];
+```
+
+## Severity Ratings
+
+| Severity | Description | Example |
+|----------|-------------|---------|
+| Critical | Major performance impact at scale | N+1 queries in API endpoint |
+| High | Noticeable performance impact | Memory leak in long-running component |
+| Medium | Suboptimal but functional | Sequential awaits on 2-3 items |
+| Low | Micro-optimization | filter+map vs reduce |
+
+## Review Format
+
+```
+## File: [path]
+
+### Line [N]: [severity] Performance
+Description of the performance issue.
+
+**Impact**: [What gets slower/uses more resources]
+**Pattern**: [Name of the anti-pattern]
+
+**Current:**
+\`\`\`
+[current code]
+\`\`\`
+
+**Suggested:**
+\`\`\`
+[optimized code]
+\`\`\`
+```

package/.workflow/specs/architecture.md.template

@@ -0,0 +1,24 @@
+# Architecture
+
+## Pattern
+
+<!-- Detected during onboarding -->
+<!-- Examples: MVC, Clean Architecture, DDD, Microservices, Monolith -->
+
+## Structure
+
+<!-- Project structure overview -->
+<!-- Key directories and their purposes -->
+
+## Key Decisions
+
+<!-- Architecture decisions made for this project -->
+<!-- Trade-offs and rationale -->
+
+## Dependencies
+
+<!-- Major dependencies and their purposes -->
+
+---
+
+*This file is auto-populated during `flow onboard`. Update manually as architecture evolves.*

package/.workflow/specs/stack.md.template

@@ -0,0 +1,33 @@
+# Tech Stack
+
+## Framework
+
+<!-- Primary framework (e.g., Next.js, NestJS, FastAPI) -->
+
+## Language
+
+<!-- Primary language (e.g., TypeScript, Python, Go) -->
+
+## Database
+
+<!-- Database system if applicable (e.g., PostgreSQL, MongoDB) -->
+
+## Package Manager
+
+<!-- npm, yarn, pnpm, pip, etc. -->
+
+## Build Tools
+
+<!-- Build and bundling tools (e.g., Vite, Webpack, esbuild) -->
+
+## Testing
+
+<!-- Test frameworks (e.g., Jest, Vitest, pytest) -->
+
+## Other Tools
+
+<!-- Linters, formatters, CI/CD tools -->
+
+---
+
+*This file is auto-populated during `flow onboard`. Update manually as stack evolves.*

package/.workflow/specs/testing.md.template

@@ -0,0 +1,36 @@
+# Testing
+
+## Test Framework
+
+<!-- Primary test framework (e.g., Jest, Vitest, pytest) -->
+
+## Test Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test file
+npm test -- path/to/test.ts
+```
+
+## Test Structure
+
+<!-- Where tests are located -->
+<!-- Naming conventions -->
+
+## Coverage
+
+<!-- Coverage requirements if any -->
+<!-- Coverage commands -->
+
+## E2E Testing
+
+<!-- E2E framework if used (e.g., Playwright, Cypress) -->
+
+---
+
+*This file is auto-populated during `flow onboard`. Update manually as testing strategy evolves.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {

package/scripts/hooks/core/routing-gate.js

@@ -18,7 +18,10 @@ const path = require('path');
 
 const { getConfig, getReadyData, PATHS } = require('../../flow-utils');
 
-const ROUTING_FLAG_PATH = path.join(PATHS.state, '.routing-pending');
+// Include session ID in flag path to prevent concurrent sessions from
+// interfering with each other. Falls back to PID-based path if no session ID.
+const SESSION_ID = process.env.CLAUDE_CODE_SESSION_ID || `pid-${process.ppid || process.pid}`;
+const ROUTING_FLAG_PATH = path.join(PATHS.state, `.routing-pending-${SESSION_ID}`);
 
 /**
  * Check if routing gate is enabled in config
@@ -32,8 +35,10 @@ function isRoutingGateEnabled() {
     if (process.env.DEBUG) {
       console.error(`[routing-gate] Config read error: ${err.message}`);
     }
-    // Fail-open: if config can't be read, don't enforce
-    return false;
+    // Fail-closed: if config can't be read, enforce the gate.
+    // Users who installed WogiFlow expect routing enforcement.
+    // Failing open here would silently bypass routing on config corruption.
+    return true;
   }
 }
 
@@ -118,8 +123,10 @@ function clearRoutingPending() {
   }
 }
 
-// Max age for routing flag before it's considered stale (5 minutes)
-const ROUTING_FLAG_TTL_MS = 5 * 60 * 1000;
+// Max age for routing flag before it's considered stale (30 minutes)
+// 5 min was too short — complex tasks with explore phases, spec generation,
+// and approval gates can take 15-20 min before first Bash call.
+const ROUTING_FLAG_TTL_MS = 30 * 60 * 1000;
 
 /**
  * Check if the routing-pending flag is set and not stale

package/scripts/hooks/entry/claude-code/user-prompt-submit.js

@@ -123,7 +123,9 @@ async function main() {
     // When users type "/wogi-start ..." directly, Claude Code expands the skill inline
     // (not through the Skill tool), so clearRoutingPending() in PreToolUse never fires.
     // Setting the flag here would create an uncleable block.
-    const isWogiCommand = typeof prompt === 'string' && /^\/(wogi-\S+)/i.test(prompt.trim());
+    // Tightened regex: only match /wogi-[lowercase-alphanumeric-hyphens] to prevent
+    // injection via crafted prompts like "/wogi-<script>" or "/wogi-../../path"
+    const isWogiCommand = typeof prompt === 'string' && /^\/wogi-[a-z0-9-]+\b/i.test(prompt.trim());
     if (!isWogiCommand) {
       try {
         setRoutingPending();

package/scripts/postinstall.js

@@ -30,13 +30,42 @@ const STATE_DIR = path.join(WORKFLOW_DIR, 'state');
 const DIR_MODE = 0o755;  // rwxr-xr-x for directories
 const FILE_MODE = 0o644; // rw-r--r-- for files
 
+// Dangerous keys for prototype pollution protection
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Safe JSON parse with prototype pollution protection.
+ * Inline copy — postinstall.js can't reliably require flow-utils.js
+ * because it runs from npm context before scripts/ is fully copied.
+ * @param {string} jsonString - JSON string to parse
+ * @param {*} defaultValue - Default value on parse failure
+ * @returns {Object} Parsed object or defaultValue
+ */
+function safeJsonParseString(jsonString, defaultValue = null) {
+  try {
+    const parsed = JSON.parse(jsonString);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return defaultValue;
+    }
+    // Check top-level keys for prototype pollution
+    for (const key of Object.keys(parsed)) {
+      if (DANGEROUS_KEYS.has(key)) {
+        return defaultValue;
+      }
+    }
+    return parsed;
+  } catch (err) {
+    return defaultValue;
+  }
+}
+
 /**
  * Safely close a file descriptor, ignoring errors
  * @param {number|null} fd - File descriptor to close
  */
 function safeClose(fd) {
   if (fd !== null) {
-    try { fs.closeSync(fd); } catch (_err) { /* intentionally ignored */ }
+    try { fs.closeSync(fd); } catch (err) { /* intentionally ignored */ }
   }
 }
 
@@ -195,11 +224,9 @@ function copyClaudeResources() {
     if (fs.existsSync(projectSettings)) {
       // Always merge hooks from package into existing settings
       try {
-        const existingRaw = JSON.parse(fs.readFileSync(projectSettings, 'utf-8'));
-        const oursRaw = JSON.parse(fs.readFileSync(packageSettings, 'utf-8'));
-        // Guard against prototype pollution from untrusted JSON
-        const existing = (existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw)) ? existingRaw : {};
-        const ours = (oursRaw && typeof oursRaw === 'object' && !Array.isArray(oursRaw)) ? oursRaw : {};
+        // Use safeJsonParseString for prototype pollution protection
+        const existing = safeJsonParseString(fs.readFileSync(projectSettings, 'utf-8'), {});
+        const ours = safeJsonParseString(fs.readFileSync(packageSettings, 'utf-8'), {});
         // Always update hooks (core WogiFlow functionality)
         existing.hooks = ours.hooks;
         existing._wogiFlowManaged = true;
@@ -224,7 +251,7 @@ function copyClaudeResources() {
         fs.copyFileSync(packageSettings, projectSettings);
         try {
           fs.chmodSync(projectSettings, FILE_MODE);
-        } catch (_err) { /* non-critical */ }
+        } catch (err) { /* non-critical */ }
       } catch (err) {
         if (process.env.DEBUG) {
           console.error(`[postinstall] settings.json initial copy failed: ${err.message}`);
@@ -288,6 +315,45 @@ function copyWorkflowManagedDirs() {
   }
 }
 
+/**
+ * Regenerate CLAUDE.md from templates (for npm update scenario)
+ * Only runs when config.json exists (project already initialized).
+ * Uses the bridge's synchronous generateRulesFile() to avoid async in postinstall.
+ */
+function regenerateClaudeMd() {
+  // Only regenerate if project is already initialized (has config.json)
+  if (!fs.existsSync(path.join(WORKFLOW_DIR, 'config.json'))) {
+    return;
+  }
+
+  try {
+    // Load the bridge module from the project's .workflow/bridges/
+    const bridgesPath = path.join(PROJECT_ROOT, '.workflow', 'bridges');
+    if (!fs.existsSync(path.join(bridgesPath, 'index.js'))) {
+      if (process.env.DEBUG) {
+        console.error('[postinstall] Bridge module not found, skipping CLAUDE.md regen');
+      }
+      return;
+    }
+
+    const { getBridge } = require(bridgesPath);
+    const bridge = getBridge({ projectDir: PROJECT_ROOT });
+
+    // generateRulesFile() is synchronous — safe to call from postinstall
+    // force: true ensures templates always win over stale CLAUDE.md
+    bridge.generateRulesFile({ force: true });
+
+    if (process.env.DEBUG) {
+      console.error('[postinstall] Regenerated CLAUDE.md from templates');
+    }
+  } catch (err) {
+    // Non-fatal — CLAUDE.md regeneration failure shouldn't break npm install
+    if (process.env.DEBUG) {
+      console.error(`[postinstall] CLAUDE.md regen failed: ${err.message}`);
+    }
+  }
+}
+
 /**
  * Check if we should be completely silent (CI only)
  */
@@ -324,6 +390,11 @@ function main() {
   // Always overwrite — these are package-managed, not user-customizable.
   copyWorkflowManagedDirs();
 
+  // Regenerate CLAUDE.md from updated templates (for npm update scenario)
+  // This ensures the AI reads fresh instructions matching the new package version.
+  // Must run AFTER copyWorkflowManagedDirs() so templates/bridges are up to date.
+  regenerateClaudeMd();
+
   // Create marker for AI to detect (unless already initialized)
   createPendingSetupMarker();
 
@@ -343,7 +414,7 @@ function main() {
       // Combine access check and open into single try-catch to avoid TOCTOU
       ttyFd = fs.openSync('/dev/tty', 'w');
       output = { write: (msg) => fs.writeSync(ttyFd, msg) };
-    } catch (_err) {
+    } catch (err) {
       // /dev/tty not available (no terminal, CI, etc.) - fallback to stderr
       ttyFd = null;
     }