wogiflow 2.1.2 → 2.2.0

package/.claude/rules/operations/git-workflows.md

@@ -0,0 +1,92 @@
+---
+alwaysApply: true
+description: "Git workflow rules for merge conflicts, conventional commits, and branch management"
+---
+
+# Git Workflow Rules
+
+## Merge Conflict Resolution
+
+When encountering merge conflicts:
+
+1. **Understand both sides** before resolving. Read the full context of both changes.
+2. **Prefer the newer implementation** when both sides modify the same logic, unless the older version has test coverage the newer lacks.
+3. **Never silently discard changes** — if unsure, ask the user which side to keep.
+4. **After resolving**: Run lint and typecheck on resolved files before committing.
+5. **Conflict markers**: If you see `<<<<<<<`, `=======`, `>>>>>>>` in any file, resolve them before any other work.
+
+```bash
+# Check for unresolved conflicts
+git diff --check
+
+# After resolving
+git add <resolved-files>
+git commit -m "fix: resolve merge conflicts in <description>"
+```
+
+## Conventional Commit Format
+
+All commits MUST use conventional commit format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | When to use |
+|------|------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace (no logic change) |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvement |
+| `test` | Adding or updating tests |
+| `chore` | Build process, tooling, dependencies |
+
+### Examples
+
+```
+feat(hooks): add InstructionsLoaded hook for rule conflict detection
+fix(routing): clear routing flag when user invokes /wogi-* commands
+docs(readme): update installation instructions for v1.8
+refactor(bridge): extract hash comparison to shared utility
+chore(deps): bump eslint to v9.x
+```
+
+### Scope
+
+Use the module or feature area: `hooks`, `bridge`, `routing`, `skills`, `plugins`, `config`, `cli`, `docs`.
+
+## Pre-Commit Review
+
+Before committing, always:
+1. Run `git diff --staged` to review what you're about to commit
+2. Verify no secrets, credentials, or `.env` files are staged
+3. Verify no debug/console.log statements left in production code
+4. Run validation (lint, typecheck) on changed files
+
+## Stash Usage
+
+Use `git stash` when:
+- Switching context to a different task mid-work
+- Pulling changes that might conflict with local work
+- Testing something on a clean working tree
+
+```bash
+git stash push -m "WIP: description of work"  # Save with message
+git stash pop                                   # Restore and remove
+git stash list                                  # See all stashes
+```
+
+## Branch Naming
+
+When creating branches (outside worktrees):
+- Feature: `feat/<short-description>`
+- Bugfix: `fix/<short-description>`
+- WogiFlow worktrees use `wogi-task-<taskId>` automatically

package/.claude/rules/operations/scratch-directory.md

@@ -0,0 +1,54 @@
+---
+alwaysApply: true
+description: "Temp files, prompts, instructions, and scratch content must go in .workflow/scratch/"
+---
+
+# Scratch Directory for Temporary Files
+
+## Rule
+
+When creating temporary, scratch, or ephemeral files — such as prompts for other projects, instructions, notes, drafts, exported configs, or any content that is NOT a permanent part of the codebase — **always write them to `.workflow/scratch/`**.
+
+## Why
+
+Without this rule, Claude creates .md files, .txt files, and other scratch content in random locations (project root, src/, docs/, etc.). This pollutes the project with files that:
+- Have no designated location, so users don't know where to find them
+- Don't get cleaned up, accumulating over time
+- May accidentally get committed to version control
+- Make `git status` noisy with untracked files
+
+## How
+
+```javascript
+// Use PATHS.scratch for temp file locations
+const { PATHS } = require('./flow-paths');
+const outputPath = path.join(PATHS.scratch, 'my-temp-file.md');
+```
+
+Or in natural language: "Save this to `.workflow/scratch/filename.md`"
+
+## Auto-Cleanup
+
+The `.workflow/scratch/` directory is **automatically cleaned at session end** by the session-end hook. Files in this directory are ephemeral — they survive the current session but are removed when the session ends.
+
+If a file needs to persist beyond a session, it belongs somewhere else:
+- Specs → `.workflow/specs/`
+- Changes → `.workflow/changes/`
+- Documentation → project docs directory
+- Configuration → `.workflow/` root
+
+## What Goes in Scratch
+
+- Prompts or instructions generated for other projects
+- Draft content being reviewed before placement
+- Temporary analysis output
+- Export/import staging files
+- Any file the user explicitly asks to "save somewhere" without specifying a location
+
+## What Does NOT Go in Scratch
+
+- Task specs (use `.workflow/specs/` or `.workflow/changes/`)
+- Configuration files (use `.workflow/`)
+- Source code (use the project's source directories)
+- Documentation (use the project's docs directory)
+- State files (use `.workflow/state/`)

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 (`;`, `&&`, `||`, `|`).
+
+**Destructive git commands** must NOT be auto-allowed. WogiFlow's `generateSettings()` scopes these to safe variants:
+
+```javascript
+// DANGEROUS - auto-allows destructive operations
+"allow": "Bash(git reset *)"    // matches git reset --hard
+"allow": "Bash(git restore *)"  // matches git restore . (discard all)
+"allow": "Bash(git clean *)"    // matches git clean -f
+
+// SAFE - only non-destructive variants auto-allowed
+"allow": "Bash(git reset HEAD *)"       // unstage files only
+"allow": "Bash(git reset --soft *)"     // soft reset, preserves changes
+"allow": "Bash(git restore --staged *)" // unstage files only
+// git reset --hard, git restore ., git clean -f require manual approval
+```
+
+**Best practices:**
+- Scope destructive commands to safe variants instead of blanket wildcards
+- `git reset --hard`, `git restore .`, `git clean -f` should always require user approval
+- 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/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/bridges/claude-bridge.js

@@ -266,7 +266,7 @@ Check \`config.json → commits\` before committing:
     sections.push(`
 ## Context Management
 
-Use \`/wogi-compact\` when:
+Use \`/wogi-pre-compact\` when:
 - After completing 2-3 tasks
 - After 15-20 messages
 - Before starting large tasks

package/.workflow/models/registry.json

@@ -100,7 +100,7 @@
       "displayName": "Claude Sonnet 4.6",
       "contextWindow": 200000,
       "contextWindowBeta": 1000000,
-      "maxOutputTokens": 64000,
+      "maxOutputTokens": 128000,
       "costTier": "standard",
       "pricing": {
         "inputPer1kTokens": 0.003,

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/.workflow/templates/claude-md.hbs

@@ -142,8 +142,8 @@ See `.claude/docs/commands.md` for complete command reference.
 | "show tasks", "what's ready", "available tasks" | `/wogi-ready` |
 | "project status", "show status", "where are we" | `/wogi-status` |
 | "check health", "workflow health", "is everything ok" | `/wogi-health` |
-| "wrap up", "end session", "that's all" | `/wogi-session-end` |
-| "compact context", "save context", "running low on context" | `/wogi-compact` |
+| "wrap up", "end session", "that's all" | `/wogi-session-end` (**intent-check required** — see note below) |
+| "compact context", "save context", "running low on context" | `/wogi-pre-compact` |
 | "show roadmap", "what's planned", "future work", "deferred items" | `/wogi-roadmap` |
 | "debug this", "investigate hypotheses", "competing theories", "parallel debug" | `/wogi-debug-hypothesis` |
 | "triage findings", "walk through review", "review findings" | `/wogi-triage` |
@@ -162,6 +162,14 @@ See `.claude/docs/commands.md` for complete command reference.
 
 **IMPORTANT**: When a user's message matches one of these patterns, immediately invoke the Skill tool with the corresponding command. Do not ask for confirmation. These `/wogi-*` commands satisfy the mandatory routing requirement — you do NOT also need to invoke `/wogi-start` when a detection match exists. `/wogi-start` is the fallback for messages that don't match this table.
 
+**Session-end intent check**: `/wogi-session-end` requires extra care. Phrases like "wrap up", "that's all", "let's finish with this" often mean "finish this topic" not "end the entire session." Only invoke `/wogi-session-end` when the user clearly intends to **stop working entirely** — not when they're concluding one topic before moving to another. Examples:
+- "that's all for today, thanks" → session-end (clear finality)
+- "let's wrap up this task and move on to the auth bug" → NOT session-end (continuing work)
+- "I'm done" → session-end (if no follow-up topic mentioned)
+- "let's finish with that and then do X" → NOT session-end (next topic follows)
+
+When in doubt, route through `/wogi-start` which will classify correctly.
+
 ## CRITICAL: Universal Entry Point — ALL Requests
 
 **ALL user messages MUST go through a `/wogi-*` command. No direct handling. No self-classification.**
@@ -274,7 +282,29 @@ Before closing any task, ensure all required gates pass (per `config.json → qu
 
 ## Context Management
 
-Use `/wogi-compact` when context is getting large. Before compacting: update progress.md, ensure request-log is current, commit work.
+Context compaction happens automatically — WogiFlow persists all critical state to disk continuously, and the PostCompact hook restores it after compaction. You do NOT need to manually run `/wogi-pre-compact` before compaction.
+
+**What survives compaction automatically** (via PostCompact hook + state files):
+- Active task ID, title, type, and acceptance criteria
+- Which criteria are completed vs pending (from durable-session.json)
+- Current workflow phase
+- Changed files list (from task-checkpoint.json)
+- Last request-log entry number
+- Routing enforcement (re-armed automatically)
+
+**`/wogi-pre-compact` is optional** — use it only when you want a detailed summary for a very long session. It is NOT required for state safety.
+
+**For L1+ tasks**: The pre-task context estimator (Step 0.25) checks if the task fits in remaining context. If it doesn't → compact BEFORE starting to avoid mid-task compaction.
+
+## Compact Instructions
+
+When compacting this conversation, preserve the following WogiFlow state:
+- The current task ID and title from `.workflow/state/ready.json` inProgress array
+- Which acceptance criteria are done vs pending
+- The current workflow phase (routing, exploring, coding, validating, completing)
+- The list of files changed in this session
+- Any spec decisions or architectural choices made during this session
+- Read `.workflow/state/task-checkpoint.json` after compaction for full state recovery
 
 ## Continuous Learning
 

package/README.md

@@ -61,7 +61,7 @@ See the [Knowledge Base](.claude/docs/knowledge-base/) for detailed documentatio
 | **Registries** | `/wogi-map`, `/wogi-map-add`, `/wogi-map-scan`, `/wogi-map-sync`, `/wogi-map-check`, `/wogi-map-index` | Component registry management |
 | **Rules** | `/wogi-decide`, `/wogi-learn`, `/wogi-rules`, `/wogi-retrospective` | Create rules, promote patterns, session retros |
 | **Research** | `/wogi-research`, `/wogi-correction` | Zero-trust verification, correction reports |
-| **Context** | `/wogi-compact`, `/wogi-context`, `/wogi-suspend`, `/wogi-resume` | Memory management, task context, suspend/resume |
+| **Context** | `/wogi-pre-compact`, `/wogi-context`, `/wogi-suspend`, `/wogi-resume` | Memory management, task context, suspend/resume |
 | **Capture** | `/wogi-capture`, `/wogi-extract-review`, `/wogi-changelog` | Quick capture, transcript extraction, changelogs |
 | **Hybrid** | `/wogi-hybrid`, `/wogi-hybrid-setup`, `/wogi-hybrid-edit`, `/wogi-hybrid-off`, `/wogi-hybrid-status` | Local LLM integration |
 | **Skills** | `/wogi-skills`, `/wogi-skill-learn`, `/wogi-setup-stack` | Skill packages, learning extraction, stack detection |

package/package.json

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