wogiflow 2.5.1 → 2.5.2

package/.claude/rules/_internal/README.md

@@ -0,0 +1,64 @@
+---
+alwaysApply: false
+description: "Meta-documentation about how project rules are organized"
+---
+# 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/_internal/document-structure.md

@@ -0,0 +1,77 @@
+---
+alwaysApply: false
+description: "All AI-context documents must use PIN markers for targeted context loading"
+globs: ".workflow/**/*.md"
+---
+
+# 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/_internal/dual-repo-management.md

@@ -0,0 +1,174 @@
+---
+alwaysApply: false
+description: "Dual-repo management rules for wogi-flow and wogiflow-cloud"
+globs: "package.json,lib/installer.js,lib/extension-points.js"
+---
+# Dual-Repo Management: wogi-flow + wogiflow-cloud
+
+**Added**: 2026-02-28
+**Source**: User directive — formalize dual-repo architecture decisions
+
+## Repository Ownership
+
+| Repo | Package | Visibility | Purpose |
+|------|---------|-----------|---------|
+| `wogi-flow` | `wogiflow` (npm) | Public (AGPL-3.0) | Free CLI, workflow engine, all local-only features |
+| `wogiflow-cloud` | `@wogiflow/teams` (client), `wogiflow-cloud-server` (server) | Private | Teams backend, client hooks, dashboard, portal logic |
+| `wogiflow-portal` | N/A (static site) | Public | wogi.ai — landing page, login, signup, knowledge base |
+
+## Hard Rule: No Teams Code in the Free Repo
+
+Team-specific logic MUST NEVER appear in `wogi-flow`. This includes:
+- Auth/login UI beyond the thin `wogi login`/`wogi logout` adapter
+- Sync engines, presence, real-time features
+- Team CRUD, roles, permissions
+- Dashboard pages
+- Server-side API routes
+
+The free repo provides **extension points** (hooks in `lib/extension-points.js`) that the cloud client plugs into. The adapter pattern is:
+- `wogi-flow` exports hook interfaces and config schema
+- `@wogiflow/teams` imports those interfaces and adds team behavior
+- All team logic executes from `@wogiflow/teams`, never from `wogiflow` core
+
+## Version Management
+
+### Independent Versions, Mutual Awareness
+
+Each repo has its own semver version. They are NOT locked together.
+
+- `wogi-flow` → `package.json` version (currently 1.6.0)
+- `wogiflow-cloud` server → `packages/server/package.json` version (currently 0.1.0)
+- `@wogiflow/teams` client → `packages/client/package.json` version (currently 0.1.0)
+
+### Cross-Repo Version File
+
+Each repo maintains a `.workflow/state/partner-versions.json` that records the last-known version of the other repo:
+
+```json
+// In wogi-flow:
+{
+  "self": { "package": "wogiflow", "version": "1.6.0" },
+  "partners": {
+    "wogiflow-cloud-server": { "version": "0.1.0", "checkedAt": "2026-02-28" },
+    "wogiflow-teams-client": { "version": "0.1.0", "minCompatible": "1.5.0", "checkedAt": "2026-02-28" }
+  }
+}
+
+// In wogiflow-cloud:
+{
+  "self": { "package": "wogiflow-cloud", "version": "0.1.0" },
+  "partners": {
+    "wogiflow": { "version": "1.6.0", "checkedAt": "2026-02-28" }
+  }
+}
+```
+
+**Update rule**: When releasing either repo, update `partner-versions.json` in BOTH repos.
+
+### Compatibility Contract
+
+The `@wogiflow/teams` client declares its minimum compatible `wogiflow` version via peerDependencies:
+
+```json
+"peerDependencies": {
+  "wogiflow": ">=1.5.0"
+}
+```
+
+**When to bump the minimum**:
+- When the free repo removes or renames an exported function that the client uses
+- When the free repo changes the shape of config.json, ready.json, or other state files
+- When the free repo changes hook interfaces (entry point signatures, event payloads)
+
+**When NOT to bump**:
+- New features added to the free repo (additive changes are always compatible)
+- Internal refactoring that doesn't change exports
+
+## Interface Contract (Public API Surface)
+
+The cloud client depends on these interfaces from `wogi-flow`. Changes to any of these require updating the client:
+
+### Exported Functions (from scripts/)
+- `flow-utils.js`: `getConfig()`, `safeJsonParse()`, `writeJson()`, `generateTaskId()`, `validateTaskId()`, `PATHS`, `getReadyData()`, `saveReadyData()`
+- `flow-session-state.js`: `trackTaskStart()`, `trackBypassAttempt()`
+- `flow-memory-blocks.js`: `setCurrentTask()`
+
+### Hook Interfaces (entry point contracts)
+- `PreToolUse` hooks receive: `{ tool, toolInput }` via stdin JSON
+- `PostToolUse` hooks receive: `{ tool, toolInput, toolResult }` via stdin JSON
+- `TaskCompleted` hooks receive: `{ taskId }` via stdin JSON
+- `SessionStart`/`SessionEnd` hooks receive: `{}` via stdin JSON
+
+### State File Formats
+- `ready.json`: `{ inProgress: [], ready: [], blocked: [], recentlyCompleted: [], backlog: [] }`
+- `config.json`: Schema documented in `config.schema.json`
+- `decisions.md`: Markdown with `## Section` / `### Rule` structure
+- `session-state.json`: `{ taskId, status, lastBriefingAt, ... }`
+
+### Config Keys Used by Cloud
+- `hooks.rules.*` — all hook toggle keys
+- `enforcement.*` — strict mode, task gating
+- `semanticMatching.*` — reuse detection thresholds
+
+**When modifying any of the above**: Check wogiflow-cloud for consumers BEFORE releasing.
+
+## Change Propagation Rules
+
+### OSS Change → Does Cloud Need Updating?
+
+| Change Type | Cloud Impact | Action Required |
+|-------------|-------------|-----------------|
+| New feature (additive) | None | No action needed |
+| Bug fix (internal) | None | No action needed |
+| Exported function renamed/removed | BREAKING | Update client, bump peerDep minimum |
+| State file format changed | BREAKING | Update client parsers |
+| Hook interface changed | BREAKING | Update client hooks |
+| Config key renamed/removed | BREAKING | Update client config readers |
+| New config key added | None (additive) | Client can optionally use it |
+
+### Cloud Change → Does OSS Need Updating?
+
+| Change Type | OSS Impact | Action Required |
+|-------------|-----------|-----------------|
+| New server feature | None | No action needed |
+| New client hook | None | No action needed |
+| Client needs new OSS export | REQUIRES | Add export to OSS, release OSS first |
+| Dashboard changes | None | Entirely separate |
+
+### Release Order
+
+1. **OSS first**: If the cloud needs a new OSS feature, release OSS first
+2. **Cloud follows**: Cloud releases independently, referencing the OSS version in peerDeps
+3. **Never**: Release cloud with a dependency on an unreleased OSS version
+
+```
+OSS v1.7.0 (adds new export)
+    ↓
+Cloud client v0.2.0 (uses new export, peerDep bumped to >=1.7.0)
+    ↓
+Cloud server v0.2.0 (may or may not change)
+```
+
+## Web Properties
+
+| Property | Repo | Purpose |
+|----------|------|---------|
+| wogi.ai (main site) | `wogiflow-portal` | Landing, login, signup, knowledge base |
+| Dashboard (admin UI) | `wogiflow-cloud/packages/dashboard/` | Team admin — served by cloud server |
+
+The portal is a separate deployment from the dashboard. The portal is public-facing (marketing + auth). The dashboard is authenticated (team management).
+
+## Verification Checklist (Before Any Release)
+
+### Releasing wogi-flow (OSS):
+1. Check `partner-versions.json` — is cloud version current?
+2. If any exported function/interface changed: grep wogiflow-cloud for consumers
+3. Run `node --check` on all modified scripts
+4. Follow GitHub Release Workflow (decisions.md)
+5. After release: update `partner-versions.json` in wogiflow-cloud
+
+### Releasing wogiflow-cloud:
+1. Check `partner-versions.json` — is OSS version current?
+2. Verify `peerDependencies.wogiflow` range includes current OSS version
+3. If client needs new OSS export: release OSS first
+4. After release: update `partner-versions.json` in wogi-flow

package/.claude/rules/_internal/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/_internal/github-releases.md

@@ -0,0 +1,71 @@
+---
+description: "GitHub release workflow - prevents race conditions in npm publish"
+alwaysApply: false
+globs: package.json
+---
+
+# GitHub Release Workflow
+
+**Source**: Repeated failures (10+ times) in npm publish automation
+**Priority**: Critical - prevents wasted releases and broken npm versions
+
+## Problem
+
+Running `git push` followed immediately by `gh release create` causes a race condition. The release tag gets created on the remote's HEAD before the push fully propagates, pointing to an old commit.
+
+## Pre-Release Quality Gate (MANDATORY)
+
+Before ANY release, verify the codebase is in a releasable state:
+
+1. **Check outstanding findings**: Read `.workflow/state/last-review.json` — if unresolved critical/high findings exist, STOP and fix them first
+2. **Run lint** (if configured): `npm run lint`
+3. **Run typecheck** (if configured): `npm run typecheck`
+4. **Verify no uncommitted changes**: `git status` should be clean
+
+The `preRelease` and `outstandingFindings` quality gates in `flow-done.js` enforce this automatically for `release` type tasks. For manual releases, check these yourself.
+
+## Correct Procedure
+
+```bash
+# 0. Verify codebase is releasable (pre-release gate)
+# (automated by flow-done.js for release-type tasks)
+
+# 1. Push commits first
+git push origin master
+
+# 2. Create tag LOCALLY on the correct commit
+git tag vX.Y.Z HEAD
+
+# 3. Push the tag explicitly
+git push origin vX.Y.Z
+
+# 4. THEN create the release (it will use the existing tag)
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
+```
+
+## Never Do This
+
+```bash
+# BAD - race condition, tag may point to wrong commit
+git push origin master && gh release create vX.Y.Z ...
+```
+
+## Recovery Procedure
+
+If a release fails with wrong version:
+
+1. Delete the bad release: `gh release delete vX.Y.Z --yes`
+2. Delete the bad remote tag: `git push origin --delete vX.Y.Z`
+3. Delete local tag if exists: `git tag -d vX.Y.Z`
+4. Follow the correct procedure above
+
+## Verification
+
+Before creating the release, verify:
+```bash
+git show vX.Y.Z --quiet --format="%H"  # Should match HEAD
+git show vX.Y.Z:package.json | grep version  # Should show X.Y.Z
+```
+
+---
+Last updated: 2026-01-30

package/.claude/rules/_internal/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/_internal/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/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/code-style/naming-conventions.md

@@ -0,0 +1,107 @@
+---
+alwaysApply: true
+description: "Naming conventions for files and code variants"
+globs: "**/*.{js,ts,jsx,tsx,mjs,cjs}"
+---
+
+# 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 (UI Projects Only)
+
+When working on projects with UI components, use consistent variant names:
+
+| Category | Values |
+|----------|--------|
+| Size | `sm`, `md`, `lg`, `xl` |
+| Intent | `primary`, `secondary`, `danger`, `success`, `warning` |
+| State | `default`, `hover`, `active`, `disabled` |
+
+Skip this section for backend-only or library projects (no UI components).
+
+## 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.
+
+### Unused Catch Variables
+
+When the catch block intentionally ignores the error, prefix with underscore: `_err`.
+
+```javascript
+// Good - _err signals "intentionally unused"
+try {
+  JSON.parse(input);
+} catch (_err) {
+  return defaultValue;
+}
+
+// Bad - looks like a bug (unused variable without underscore)
+try {
+  JSON.parse(input);
+} catch (err) {
+  return defaultValue;
+}
+```
+
+This convention is used across 100+ files in the codebase and satisfies no-unused-vars lint rules.
+
+## Default Value Operators: `||` vs `??`
+
+Use **nullish coalescing (`??`)** for defaults where the left operand could legitimately be `0`, `false`, or `""`.
+
+Use **logical OR (`||`)** only when falsy values (0, false, empty string) should genuinely fall through to the default.
+
+```javascript
+// Use ?? — timeout=0 is valid (means "no timeout"), not "use default"
+this.timeout = options.timeout ?? TIMEOUTS.HTTP_DEFAULT;
+
+// Use ?? — numeric config values where 0 is meaningful
+const retries = config.maxRetries ?? 3;
+const threshold = config.similarityThreshold ?? 0.5;
+
+// Use ?? — boolean config where false is the intended value
+const strictMode = config.enforcement?.strictMode ?? false;
+
+// Use ?? — array/object defaults guarding against null/undefined
+const items = data.inProgress ?? [];
+const settings = config.hybrid ?? {};
+
+// Use || — empty string should fall through to a display default
+const branch = status.git.branch || 'unknown';
+
+// Use || — lookup fallback where undefined means "not found"
+const name = cliNames[type] || type;
+
+// Use || — join() returns "" for empty arrays, want a fallback message
+const summary = facts.join('; ') || 'No data available';
+```
+
+**Rule of thumb**: If you are defaulting a config value, numeric parameter, boolean flag, or array/object from a potentially-null source, use `??`. If you are providing a display fallback where empty string should show a placeholder, use `||`.

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/settings.json

@@ -36,6 +36,7 @@
     ],
     "PostToolUse": [
       {
+        "matcher": "Edit|Write|Bash",
         "hooks": [
           {
             "type": "command",

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/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/lib/workspace.js

@@ -1293,9 +1293,10 @@ function startWorkerSession(cwd) {
     WOGI_WORKSPACE_ROOT: workspaceRoot
   };
 
-  // Launch Claude Code with the channel
+  // Launch Claude Code — it auto-loads .mcp.json from cwd,
+  // which contains the wogi-workspace-channel server config
   try {
-    execSync('claude --dangerously-load-development-channels server:wogi-workspace-channel', {
+    execSync('claude', {
       cwd,
       env,
       stdio: 'inherit'

package/package.json

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