wogiflow 1.0.46 → 1.0.47

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/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,143 @@
+---
+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

package/.workflow/bridges/claude-bridge.js

@@ -58,28 +58,91 @@ class ClaudeBridge extends BaseBridge {
   }
 
   /**
-   * Generate CLAUDE.md from Handlebars template
+   * Generate CLAUDE.md from Handlebars-like template
+   * Supports: {{variable}}, {{config.path}}, {{#if}}, {{#each}}, {{/if}}, {{/each}}
    */
   generateFromTemplate(templatePath, config) {
     const template = fs.readFileSync(templatePath, 'utf-8');
-
-    // Simple template variable replacement (not full Handlebars)
     let content = template;
 
+    // Process {{#if config.path.to.value}}...{{/if}} blocks
+    // Non-greedy match to handle nested conditions
+    content = this.processConditionals(content, config);
+
+    // Process {{#each array}}...{{/each}} blocks
+    content = this.processEachBlocks(content, config);
+
     // Replace {{variable}} patterns
     content = content.replace(/\{\{(\w+)\}\}/g, (match, key) => {
       return config[key] || match;
     });
 
     // Replace {{config.path.to.value}} patterns
-    content = content.replace(/\{\{config\.([^}]+)\}\}/g, (match, path) => {
-      const value = this.getNestedValue(config, path);
+    content = content.replace(/\{\{config\.([^}]+)\}\}/g, (match, configPath) => {
+      const value = this.getNestedValue(config, configPath);
       return value !== undefined ? String(value) : match;
     });
 
+    // Replace {{timestamp}} with current time
+    content = content.replace(/\{\{timestamp\}\}/g, new Date().toISOString());
+
+    return content;
+  }
+
+  /**
+   * Process {{#if condition}}...{{/if}} blocks
+   */
+  processConditionals(content, config) {
+    // Regex to match {{#if path}}...{{/if}} - handles nested by processing innermost first
+    const ifRegex = /\{\{#if\s+([^}]+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+
+    let lastContent;
+    // Keep processing until no more changes (handles nested conditions)
+    do {
+      lastContent = content;
+      content = content.replace(ifRegex, (match, condition, body) => {
+        // Evaluate condition
+        let value;
+        if (condition.startsWith('config.')) {
+          value = this.getNestedValue(config, condition.replace('config.', ''));
+        } else if (condition === 'skills') {
+          value = config.skills?.installed?.length > 0;
+        } else {
+          value = this.getNestedValue(config, condition);
+        }
+
+        // If truthy, return the body (stripped of the conditionals)
+        // If falsy, return empty string
+        return value ? body : '';
+      });
+    } while (content !== lastContent);
+
     return content;
   }
 
+  /**
+   * Process {{#each array}}...{{/each}} blocks
+   */
+  processEachBlocks(content, config) {
+    const eachRegex = /\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g;
+
+    return content.replace(eachRegex, (match, arrayName, body) => {
+      let array;
+      if (arrayName === 'skills') {
+        array = config.skills?.installed || [];
+      } else {
+        array = config[arrayName] || [];
+      }
+
+      if (!Array.isArray(array) || array.length === 0) {
+        return '';
+      }
+
+      // Replace {{this}} in body with each array item
+      return array.map(item => body.replace(/\{\{this\}\}/g, String(item))).join('');
+    });
+  }
+
   /**
    * Generate default CLAUDE.md when no template exists
    */

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.*