wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/future-features.md

@@ -0,0 +1,277 @@
+# Future Features
+
+Planned and considered features for WogiFlow.
+
+---
+
+## Status Legend
+
+| Status | Meaning |
+|--------|---------|
+| **Planned** | Will be implemented |
+| **Backlog** | On request or when needed |
+| **Considering** | Under evaluation |
+| **Skipped** | Not planning to implement |
+
+---
+
+## Planned Features
+
+### Team Observability Dashboard
+
+**Status**: Planned (with team tier launch)
+
+Web UI for team-wide visibility:
+- All runs with status
+- Per-step spans with inputs/outputs
+- Retry history and failure context
+- Team-wide task dashboard
+- Role-based access (admin, lead, member)
+
+**Trigger**: Team tier launch with hosted database
+
+---
+
+### Enhanced Model Stats
+
+**Status**: Planned
+
+Track detailed success metrics per model:
+
+```json
+{
+  "ollama-qwen": {
+    "successRate": 0.87,
+    "avgLatencyMs": 4500,
+    "failuresByCategory": {
+      "import_error": 12,
+      "type_error": 5
+    },
+    "byTaskType": {
+      "create-component": { "success": 45, "fail": 3 },
+      "fix-bug": { "success": 22, "fail": 8 }
+    }
+  }
+}
+```
+
+**Trigger**: Users asking "which model is best for X?"
+
+---
+
+### Tiered Learning Thresholds
+
+**Status**: Planned
+
+Smarter auto-application of learned patterns:
+
+```javascript
+const LEARNING_TIERS = {
+  AUTO_APPLY: { minSuccessRate: 0.9, minSamples: 5 },
+  APPLY_WITH_LOG: { minSuccessRate: 0.7, minSamples: 3 },
+  QUEUE_FOR_REVIEW: { minSuccessRate: 0, minSamples: 0 }
+};
+```
+
+**Trigger**: Model adapter needs smarter auto-apply logic
+
+---
+
+## Backlog Features
+
+### Quality Gate Confidence
+
+**Status**: Backlog
+
+Don't apply low-confidence changes automatically:
+
+```javascript
+const confidenceMarkers = {
+  high: ["I'm confident", "This will work", "Straightforward"],
+  low: ["I think", "might work", "not entirely sure"]
+};
+```
+
+**Trigger**: When bad outputs are frequently applied
+
+---
+
+### Context Priority Scoring
+
+**Status**: Backlog
+
+Smarter context selection than "include everything":
+
+```javascript
+const CONTEXT_PRIORITIES = {
+  required_types: 1.0,      // Always include
+  target_file: 0.95,        // Almost always
+  related_imports: 0.8,     // Usually helpful
+  patterns: 0.7,            // Good to have
+  examples: 0.5,            // Nice to have
+  full_files: 0.3           // Only if space
+};
+```
+
+**Trigger**: If context overflow becomes common
+
+---
+
+### Formalized Model Registry
+
+**Status**: Backlog
+
+Structured capability definitions per model:
+
+```json
+{
+  "models": {
+    "gpt-4o-mini": {
+      "provider": "openai",
+      "contextWindow": 128000,
+      "costTier": "cheap",
+      "capabilities": ["code-generation", "structured-output"],
+      "structuredOutputReliability": "high"
+    }
+  }
+}
+```
+
+**Trigger**: When supporting 5+ executor models
+
+---
+
+## Multi-Model Features
+
+Only implement if users have 3+ models configured.
+
+### Multi-Model Orchestration
+
+**Status**: Considering
+
+Route different tasks to optimal models:
+
+```json
+{
+  "modelRouting": {
+    "orchestration": "claude-opus",
+    "exploration": "claude-haiku",
+    "frontend": "gemini-pro",
+    "debugging": "gpt-5",
+    "documentation": "claude-sonnet"
+  }
+}
+```
+
+**Trigger**: Users want to optimize cost/quality tradeoffs
+**Risk**: Complexity, API key management, cost tracking
+
+---
+
+### Task Router
+
+**Status**: Backlog
+
+Automatically route task types to best models.
+
+**Trigger**: Users with 3+ models asking for routing
+**Risk**: Over-engineering for single-model users
+
+---
+
+### Parallel Dispatch
+
+**Status**: Backlog
+
+Execute independent subtasks on multiple models simultaneously.
+
+**Trigger**: Users request parallel execution for speed
+**Risk**: Complexity for unclear gain
+
+---
+
+## Skipped Features
+
+We're skeptical these add value without strong evidence.
+
+### Structured JSON Contract
+
+**Why Skipped**: Local LLMs can't reliably produce JSON
+**Would Reconsider If**: New models achieve 95%+ JSON reliability
+**Current Solution**: `flow-response-parser.js` handles messy output
+
+---
+
+### SQLite Telemetry
+
+**Why Skipped**: JSON files work fine for 50 runs/day
+**Would Reconsider If**: Users need complex queries across runs
+**Concerns**: Native dependency, not human-readable, overkill
+
+---
+
+### Prompt Fragment System
+
+**Why Skipped**: Current Handlebars templates work fine
+**Would Reconsider If**: Templates become unmanageable (20+)
+
+---
+
+## Recently Implemented
+
+These were on the backlog but have been completed:
+
+| Feature | Implementation |
+|---------|---------------|
+| Jira Integration | flow-jira-integration.js - `flow jira list/sync/push` |
+| Linear Integration | flow-linear-integration.js - `flow linear list/sync/push` |
+| Cascade Fallback | flow-cascade.js - `flow cascade status/reset/config` |
+| Background Sync Daemon | flow-sync-daemon.js - `flow sync-daemon start/stop/status` |
+| PRD Management | flow-prd-manager.js - `flow prd load/context/list/clear` |
+| Memory Sync | flow-memory-sync.js - `flow memory-sync --auto` |
+| Entropy Monitor | flow-entropy-monitor.js - `flow entropy --auto` |
+| Model Registry & Stats | flow-models.js - `flow models list/info/route/stats` |
+| Model Router | flow-model-router.js - `flow route "<task>"` |
+| Multi-Approach | flow-multi-approach.js - `flow multi-approach` |
+| Complexity Assessment | flow-complexity.js - `flow complexity "<task>"` |
+| Metrics & Analysis | flow-metrics.js - `flow metrics --problems` |
+| Release Channels | lib/release-channel.js - `flow channel show/set/list` |
+| Tiered Learning | flow-tiered-learning.js - `flow learning tiers/stats` |
+| Failure Category Enum | `ERROR_CATEGORIES` in flow-adaptive-learning.js |
+| Strategy Effectiveness | `flow hybrid learning effectiveness` |
+| Learning Deduplication | 7-day window in flow-adaptive-learning.js |
+| Community Contribution | `flow hybrid learning contribute --auto-pr` |
+| Damage Control System | flow-damage-control.js |
+| Auto-Inference Verification | flow-task-enforcer.js |
+| Durable Sessions | flow-durable-session.js |
+| Suspend/Resume | flow-suspend.js, flow-resume.js |
+| agent_requested Rules | Rules have `alwaysApply` frontmatter for smart loading |
+| Component Index Freshness | Post-task triggers, stale checks, git hooks |
+| Guided Edit Mode | `/wogi-guided-edit` for step-by-step multi-file changes |
+| Git Hooks Setup | `flow-setup-hooks.js` for pre-commit automation |
+
+---
+
+## How This Backlog Works
+
+1. **Review Quarterly**: Are users asking for any of these?
+2. **Promote on Demand**: Move items up when users request them
+3. **Delete if Stale**: Remove items no one asks about in 6 months
+4. **Track Triggers**: Note what would make each feature valuable
+
+---
+
+## Requesting Features
+
+To request a feature from this backlog:
+1. Open an issue with use case
+2. Describe the pain point
+3. If compelling, feature gets promoted
+
+---
+
+## Related
+
+- [Task Execution](./02-task-execution/) - Core execution features
+- [Self-Improvement](./03-self-improvement/) - Learning system
+- [Hybrid Mode](./02-task-execution/02-execution-loop.md#hybrid-mode) - Multi-model basics

package/.claude/docs/stack.md

@@ -0,0 +1,25 @@
+# Tech Stack
+
+## Runtime
+- Node.js 18+
+
+## Package Manager
+- npm
+
+## Languages
+- JavaScript (CommonJS)
+- Shell scripts (Bash)
+
+## Key Dependencies
+- fs, path (Node built-ins)
+- crypto (for hash-based IDs)
+- child_process (for git operations)
+
+## Development Tools
+- Git for version control
+- No build system (direct Node.js execution)
+
+---
+
+Generated: 2026-01-11
+Last synced: 2026-01-11

package/.claude/docs/testing.md

@@ -0,0 +1,71 @@
+# Testing Strategy
+
+<!-- PINS: test-commands, verification-gates, windows-testing -->
+
+## Current State
+<!-- PIN: test-commands -->
+
+- No formal test framework configured
+- Manual testing via CLI commands
+
+## Test Commands
+```bash
+# Health check
+./scripts/flow health
+
+# Verify workflow files
+./scripts/flow verify
+
+# Check knowledge sync
+./scripts/flow knowledge-sync status
+```
+
+## Verification Gates
+<!-- PIN: verification-gates -->
+
+Configured in `config.json → qualityGates`:
+- Lint check
+- TypeScript type check
+- Test execution (when configured)
+
+## Future Considerations
+- Add Jest or Vitest for unit tests
+- Add integration tests for CLI commands
+- Add E2E tests for full workflow scenarios
+
+## Windows Testing Checklist
+<!-- PIN: windows-testing -->
+
+When testing WogiFlow on Windows with Claude Code 2.1.7+:
+
+### Path Handling
+- [ ] Verify temp directory paths work correctly
+  - Windows paths may contain backslash sequences like `C:\temp` or `C:\new` where `\t` and `\n` could be misinterpreted as tab and newline escape sequences if not handled properly
+- [ ] Confirm `path.join()` creates valid Windows paths
+- [ ] Test file operations in OneDrive/Dropbox-synced directories
+
+### File System
+- [ ] Check no false "file modified" errors with cloud sync tools
+- [ ] Verify antivirus scanner compatibility (Windows Defender)
+- [ ] Test file watching doesn't trigger spurious updates
+
+### Bash Commands
+- [ ] Confirm bash commands execute correctly via Claude Code
+- [ ] Verify escape sequences in paths are handled properly
+- [ ] Test commands with spaces in directory names
+
+### Quick Smoke Test
+```powershell
+# In PowerShell
+npm install wogiflow
+npx flow health
+npx flow status
+npx flow ready
+```
+
+**Note**: Claude Code 2.1.7 fixed several Windows-specific issues including path escape sequence handling and false "file modified" errors with cloud sync tools. If you encounter problems, ensure Claude Code is updated.
+
+---
+
+Generated: 2026-01-11
+Last synced: 2026-01-14

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.