wogiflow 1.8.8 → 1.9.0

package/.claude/commands/wogi-review.md

@@ -813,177 +813,65 @@ Then present 4 options:
 - Triage will handle fix/task/skip/dismiss decisions per finding
 - Proceed to step 5.4 after triage completes
 
-**5.3b. If user chooses fix (Option 1 or 2) — SEVERITY-ROUTED FIX LOOP**:
-
-**BEFORE applying any fixes, create a tracked fix task in `ready.json` inProgress:**
-
-1. Generate a fix task ID: `wf-cr-XXXXXX` (first 6 chars of a hash based on review date + finding count)
-2. Count findings to fix (all for Option 1, critical/high only for Option 2)
-3. Read `ready.json`, add fix task to `inProgress` array:
-   ```json
-   {
-     "id": "wf-cr-XXXXXX",
-     "title": "Fix N review findings from [review-id or task-id]",
-     "type": "fix",
-     "feature": "review",
-     "status": "in_progress",
-     "priority": "P0",
-     "startedAt": "[ISO timestamp]"
-   }
-   ```
-4. Write updated `ready.json` — the task-gate (PreToolUse) will now allow Edit/Write operations
-5. Display: `Created fix task: wf-cr-XXXXXX — Fix N review findings`
-
-**ONLY AFTER the task exists in inProgress**, proceed with the severity-routed fix loop.
-
-**Severity Routing Table** (read `config.reviewFix.severityRouting`):
-
-| Severity | autoFixable | Security? | Route |
-|----------|------------|-----------|-------|
-| critical | any | any | Full `/wogi-start` loop |
-| high | false | any | Full `/wogi-start` loop |
-| high | true | yes | Full loop (security always gets full review) |
-| high | true | no | Light fix loop |
-| medium/low | any | yes | Light fix + security flag (display to user even when auto-fixable) |
-| medium/low | any | no | Light fix loop |
-
-**Full loop** (for critical/high findings): Convert to TodoWrite items as individual todos. For each:
-- Mark in_progress
-- Apply fix
-- Run targeted verification (node --check, lint, typecheck)
-- Mark completed
-
-**Light fix loop** (for medium/low auto-fixable findings):
-1. Apply fix (Edit tool)
-2. Verify: `node --check <file>` + lint + typecheck
-3. If PASS → mark fixed
-4. If FAIL → retry once, then escalate to manual/task
-
-Light fix loop does NOT include: spec generation, explore phase, approval gate, or criteria check.
-
-- After all fixes: Re-run verification gates (lint, typecheck, tests)
-- **Fix loop iteration cap**: Maximum 3 re-verify cycles. If new issues keep appearing after 3 iterations, stop and present remaining issues to the user rather than continuing automatically.
-
-**AFTER the fix loop completes**, move the fix task to recentlyCompleted:
-1. Read `ready.json`
-2. Remove the fix task from `inProgress`
-3. Add it to `recentlyCompleted` with `completedAt` timestamp
-4. Write updated `ready.json`
-5. Display: `Fix task wf-cr-XXXXXX completed and moved to recentlyCompleted`
-
-This ensures:
-- The PreToolUse task-gate allows edits during the fix loop (active task exists)
-- After completion, no active task exists → task-gate blocks subsequent untracked edits
-- All fix work is tracked and visible in the workflow
-
-**5.3c. Same-session detection + persistent task creation for unfixed findings (ALL options)**:
-
-After the fix loop completes (Options 1/2), or immediately (Option 4), handle unfixed findings with **origin-aware persistence**. This ensures nothing gets silently lost AND creates traceability.
-
-**Step 1: Same-session detection** (read `config.originTaskTracing`):
-
-When `config.originTaskTracing.annotateCompletedTasks` is true:
-
-1. Read `ready.json` → `recentlyCompleted` array
-2. For each completed task, check if `completedAt` is within the `sameSessionWindow` (default: 2 hours from now)
-3. For each unfixed finding, check if `finding.file` was changed by a recent completed task:
-   - Run `git log --format="%H" -1 -- [finding.file]` to get the last commit that touched the file
-   - Check if that commit message contains a task ID from `recentlyCompleted` (e.g., `wf-XXXXXXXX` in the commit message)
-   - Alternatively, check if the finding's file path appears in the completed task's known changed files
-4. If a match is found → this is a **same-session finding** for that origin task
-
-**Step 2: Annotate completed tasks with same-session findings**:
-
-For findings that match a same-session completed task:
-
-1. Add a `reviewFindings` array to the completed task in `recentlyCompleted`:
-   ```json
-   {
-     "id": "wf-existing-task",
-     "title": "...",
-     "status": "completed",
-     "reviewFindings": [
-       {
-         "id": "[finding.id]",
-         "severity": "[finding.severity]",
-         "category": "[finding.category]",
-         "file": "[finding.file]",
-         "line": "[finding.line]",
-         "issue": "[finding.issue]",
-         "recommendation": "[finding.recommendation]",
-         "reviewDate": "[ISO]",
-         "status": "unfixed"
-       }
-     ]
-   }
-   ```
-2. Do NOT create a separate `wf-rv-` task for these findings — they live on the completed task
-3. Display: `Annotated task [id] with N review findings (same-session)`
-
-**Step 3: Create persistent tasks for remaining (non-same-session) findings**:
-
-For findings that do NOT match a same-session task, create `wf-rv-` tasks with origin tracing:
-
-1. **Duplicate check**: Search `ready.json` for existing task with matching `finding.id` in the `finding` field. If a task already exists for this finding, skip creation.
-2. **Generate ID**: `wf-rv-XXXXXXXX` (8-char hash of `finding.id` + reviewDate)
-3. **Resolve origin task** (when `config.originTaskTracing.traceOrigin` is true):
-   - Run `git log --format="%H %s" -1 -- [finding.file]` to find the last commit
-   - Extract task ID from commit message (pattern: `wf-XXXXXXXX`)
-   - Look up the task in `recentlyCompleted` to get `{ id, title, type, feature }`
-   - If no task ID found in commit → set `originTask: null`
-4. **Map severity → priority**: critical→P0, high→P1, medium→P2, low→P3
-5. **Create task** in `ready.json` `ready` array:
-   ```json
-   {
-     "id": "wf-rv-XXXXXXXX",
-     "title": "Review fix: [issue truncated to 80 chars]",
-     "type": "fix",
-     "feature": "review",
-     "source": "review",
-     "reviewDate": "[ISO]",
-     "originTask": {
-       "id": "[origin task ID or null]",
-       "title": "[origin task title]",
-       "type": "[origin task type]",
-       "feature": "[origin task feature]"
-     },
-     "finding": {
-       "id": "[finding.id]",
-       "severity": "[finding.severity]",
-       "category": "[finding.category]",
-       "file": "[finding.file]",
-       "line": "[finding.line]",
-       "issue": "[finding.issue]",
-       "recommendation": "[finding.recommendation]",
-       "autoFixable": "[finding.autoFixable]"
-     },
-     "status": "ready",
-     "priority": "P0-P3",
-     "batchable": true,
-     "batchKey": "[file]|[category]",
-     "createdAt": "[ISO]"
-   }
-   ```
+**5.3b. If user chooses fix (Option 1 or 2) — ROUTED FIX VIA /wogi-start**:
+
+**CRITICAL: Do NOT manually edit `ready.json` to create fix tasks. This is a routing bypass.**
+
+All fix work MUST be routed through `/wogi-start`, which creates properly tracked tasks through the routing system. This ensures fixes go through the full pipeline: explore → spec → implementation → verification → quality gates → map updates → request log.
+
+**Procedure:**
+
+1. Compose a fix request summarizing findings to fix (all for Option 1, critical/high only for Option 2)
+2. Invoke `/wogi-start "Fix N review findings: [brief summary of top issues]"`
+3. `/wogi-start` will:
+   - Create a properly tracked task via `generateTaskId()`
+   - Route it through the standard pipeline (L2 or L3 based on scope)
+   - Each finding becomes an acceptance criterion
+   - All quality gates, maps, and logs are updated through the normal flow
+4. The fix task proceeds through the standard WogiFlow execution loop
+
+**Finding-to-criteria mapping:**
+
+| Finding severity | Acceptance criterion format |
+|-----------------|---------------------------|
+| critical/high | Individual criterion per finding with Given/When/Then |
+| medium | Grouped by file: "Fix N medium issues in [file]" |
+| low | Grouped by category: "Fix N [category] issues" |
+
+**Why this matters:** Manual ready.json editing bypasses explore, spec, standards checks, wiring verification, map updates, and request logging. This is the #1 cause of incomplete fixes and state file drift.
 
-**Step 4: Learning signal detection** (when `config.originTaskTracing.learningSignal.enabled` is true):
+**After `/wogi-start` completes the fix task**, the standard completion flow handles:
+- Moving task to recentlyCompleted
+- Updating request-log.md
+- Updating maps if needed
+- Running quality gates
+- Committing changes
 
-After all tasks are created, check for patterns:
+**5.3c. Handling unfixed findings (ALL options)**:
 
-1. Collect all `originTask` references from newly created `wf-rv-` tasks AND existing `wf-rv-` tasks in `ready.json`
-2. Group by `originTask.type` and `originTask.feature`
-3. If any group has >= `config.originTaskTracing.learningSignal.threshold` (default: 3) fix tasks:
-   - Add entry to `feedback-patterns.md`:
-     ```
-     | [date] | review-origin-pattern-[type/feature] | Tasks of type "[type]"/feature "[feature]" consistently generate review fixes (N instances) | N | Investigate |
-     ```
-   - Display warning:
-     ```
-     ⚠️ LEARNING SIGNAL: Tasks of type "[type]"/feature "[feature]" have generated N review fixes.
-        This suggests a systematic issue with how these tasks are implemented.
-        Consider: /wogi-decide "review checklist for [type] tasks"
-     ```
+After the fix loop completes (Options 1/2), or immediately (Option 4), handle unfixed findings.
 
-**Step 5: Update `last-review.json`**: For each finding that got a task, add `"taskCreated": "wf-rv-XXXXXXXX"`. For same-session annotations, add `"annotatedOn": "[origin task ID]"`. Set `"triaged": true` on the review.
+**CRITICAL: Do NOT manually edit `ready.json` to create tasks for unfixed findings.** All task creation MUST go through `/wogi-start`.
+
+**For unfixed findings that need separate tasks:**
+
+1. Compose a summary of remaining unfixed findings grouped by severity
+2. Invoke `/wogi-start "Fix N remaining review findings: [summary]"` for each batch
+3. `/wogi-start` handles task creation, routing, and execution through the standard pipeline
+
+**For findings the user chose to defer (Option 4):**
+
+1. Update `last-review.json` — set `"status": "deferred"` on each finding
+2. Display: `N findings deferred. Run /wogi-review-fix --pending to process later.`
+3. Do NOT create tasks in ready.json directly — when the user runs `/wogi-review-fix --pending`, it reads `last-review.json` and routes each finding through `/wogi-start`
+
+**Learning signal detection:**
+
+After completing fixes, check for recurring patterns:
+1. If 3+ findings share the same `category` or `file` → log to `feedback-patterns.md`
+2. Display warning suggesting `/wogi-decide` to create a preventive rule
+
+**Update `last-review.json`**: Set `"triaged": true` on the review after all findings are addressed (fixed, deferred, or dismissed).
 
 **Config toggles** (all in `config.originTaskTracing`):
 - `annotateCompletedTasks: false` → Skip same-session detection, all findings create standalone tasks
@@ -1398,45 +1286,29 @@ After ALL review phases complete (1 through 4), execute the fix-and-verify loop:
 ┌─────────────────────────────────────────────────────────────┐
 │  POST-REVIEW WORKFLOW                                        │
 ├─────────────────────────────────────────────────────────────┤
-│  0. CREATE FIX TASK: Add wf-cr-XXXXXX to ready.json         │
-│     → MUST exist before any edits (task-gate enforces)       │
-│  1. TRACK: Convert issues to TodoWrite items                 │
-│     → Critical/High: Individual todos                        │
-│     → Medium/Low: Grouped by category                        │
-│  2. FIX LOOP: For each issue:                                │
-│     → Mark todo in_progress                                  │
-│     → Apply fix                                              │
-│     → Run targeted verification (lint/typecheck on file)     │
-│     → Mark todo completed                                    │
-│  3. RE-VERIFY: Run full verification gates again             │
-│     → All gates must pass                                    │
-│     → If new issues found, add to todo list                  │
-│  4. COMPLETE TASK: Move wf-cr-XXXXXX to recentlyCompleted    │
-│  5. ARCHIVE: Save review report to .workflow/reviews/        │
-│  6. SIGN-OFF: User approves review complete                  │
+│  0. ROUTE FIX: Invoke /wogi-start with fix request           │
+│     → Do NOT manually edit ready.json                        │
+│     → /wogi-start creates task through routing system        │
+│  1. /wogi-start PIPELINE handles:                            │
+│     → Explore, spec, implementation, verification            │
+│     → Each finding = acceptance criterion                    │
+│     → Quality gates, maps, logs all updated                  │
+│  2. ARCHIVE: Save review report to .workflow/reviews/        │
+│  3. SIGN-OFF: User approves review complete                  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Step 0: Create Fix Task (MANDATORY before any edits)
+### Step 0: Route Fix Work Through /wogi-start (MANDATORY)
 
-**Before converting findings to todos or applying any fixes**, create a tracked task:
+**Do NOT manually edit `ready.json` to create fix tasks.** This bypasses the routing system and results in incomplete fixes (no explore, no spec, no standards check, no map updates).
 
-1. Generate task ID: `wf-cr-XXXXXX` (6-char hash of review date + finding count)
-2. Read `ready.json`, add to `inProgress`:
-   ```json
-   {
-     "id": "wf-cr-XXXXXX",
-     "title": "Fix N review findings from [review-id or task-id]",
-     "type": "fix",
-     "feature": "review",
-     "status": "in_progress",
-     "priority": "P0",
-     "startedAt": "[ISO timestamp]"
-   }
-   ```
-3. Write `ready.json` — the PreToolUse task-gate will now allow Edit/Write operations
+Instead, invoke `/wogi-start "Fix N review findings: [summary]"` which:
+1. Creates a properly tracked task via `generateTaskId()`
+2. Routes through the standard pipeline (explore → spec → implementation → verification → quality gates)
+3. Each finding becomes an acceptance criterion in the spec
+4. All state files, maps, and logs are updated through the normal flow
 
-**Why this is required**: The PreToolUse task-gate hard-blocks Edit/Write when no active task exists in `ready.json` inProgress. Without this step, the fix loop's edits would be blocked.
+**Why routing matters**: The PreToolUse task-gate requires an active task for Edit/Write operations. `/wogi-start` creates this task through the proper routing system, ensuring all pipeline stages execute. Manual ready.json editing creates a "fake" task that bypasses the pipeline.
 
 ### Step 1: Issue Tracking
 
@@ -1501,16 +1373,15 @@ If new issues are discovered during re-verification:
 2. Continue the fix loop
 3. Re-verify again
 
-### Step 4: Complete Fix Task
-
-**After all fixes pass verification**, move the fix task to recentlyCompleted:
+### Step 4: Task Completion (Handled by /wogi-start)
 
-1. Read `ready.json`
-2. Remove `wf-cr-XXXXXX` from `inProgress`
-3. Add it to `recentlyCompleted` with `completedAt` timestamp
-4. Write `ready.json`
+Fix task completion is handled automatically by the `/wogi-start` execution loop (Step 5: Finalize). This includes:
+- Moving the task to recentlyCompleted in ready.json
+- Updating request-log.md
+- Running quality gates
+- Committing changes
 
-**After this step, no active task exists** — the PreToolUse task-gate will block any subsequent Edit/Write operations until the user starts a new task via `/wogi-start`.
+**Do NOT manually edit ready.json** to move tasks between arrays. The `/wogi-start` pipeline handles this through its standard completion flow.
 
 ### Step 5: Archive Review Report
 

package/.claude/commands/wogi-start.md

@@ -162,6 +162,15 @@ Launch all in parallel. When `config.hybrid.enabled`, route via `model` paramete
 
 **After agents complete**: Display consolidated research summary covering codebase analysis, best practices, version info, risks, standards, and consumer impact.
 
+**REUSE GATE (MANDATORY)**: After consolidating agent results, check for reuse candidates:
+1. Collect all reuse candidates reported by Agent 1 (domain-keyword search) and Agent 5 (registry scan)
+2. If ANY reuse candidate has purpose overlap with planned new code → **STOP and present to user**:
+   - Show each candidate: name, path, purpose, similarity
+   - Ask: "Use existing / Extend existing / Create new (explain why)"
+   - Implementation BLOCKED until user decides on each candidate
+3. If no reuse candidates found → proceed normally
+4. This gate runs BEFORE spec generation — catching reuse early prevents wasted implementation
+
 **For L1/L0 tasks**: Offer to deepen research (exhaustive search, load all skills, full dependency tree).
 
 **Fallback**: If agents fail, log warning and proceed with remaining. Consumer Impact failure on refactor tasks = HARD BLOCK (require user confirmation). See `.claude/docs/explore-agents.md` for details.
@@ -232,11 +241,17 @@ After implementing all scenarios, BEFORE quality gates:
 
 Run `node scripts/flow-wiring-verifier.js wf-XXXXXXXX`
 
-For each created file, verify it's imported/used somewhere:
+**Forward wiring** — For each created file, verify it's imported/used somewhere:
 - Entry points (index.ts, App.tsx, *.config.ts, tests) don't need imports
 - Components MUST be imported in a parent. Hooks MUST be called. Utilities MUST be imported.
 - If NOT wired: identify where to import, wire it up, re-verify.
 
+**Removal impact** (v1.9.3) — For each removed export, type member, or identifier, verify no consumers still reference it:
+- Runs automatically as part of the `integrationWiring` quality gate
+- Detects orphaned references: removed type union members, exported names, component references, string literal IDs (e.g., tab IDs, route keys)
+- If orphaned references found: update consumers to remove stale references, re-verify.
+- CLI: `node scripts/flow-wiring-verifier.js removal-check [files...]`
+
 ### Step 3.7: Standards Compliance Check (MANDATORY)
 
 Run `node scripts/flow-standards-gate.js wf-XXXXXXXX [changed-files...]`
@@ -253,7 +268,23 @@ If violations found: fix, re-run, only proceed when all pass. Violations auto-re
 
 **First**: Run `node scripts/flow-spec-verifier.js verify wf-XXXXXXXX` — verify all spec deliverables exist. If missing → STOP, create them.
 
-**Then**: Check `config.qualityGates` for task type: tests, requestLogEntry, appMapUpdate, noNewFeatures (refactors).
+**Then**: Check `config.qualityGates` for task type. Gates are type-specific:
+- **feature**: loopComplete, tests, appMapUpdate, requestLogEntry, integrationWiring, standardsCompliance
+- **bugfix**: loopComplete, tests, requestLogEntry, standardsCompliance, learningEnforcement
+- **refactor**: loopComplete, tests, noNewFeatures, smokeTest, standardsCompliance
+- **chore**: requestLogEntry, outstandingFindings
+- **release**: requestLogEntry, outstandingFindings, preRelease
+- **fix**: loopComplete, requestLogEntry, standardsCompliance
+
+**Fallback behavior**: Task types not listed above (docs, style, test, perf, etc.) inherit the **feature** gates. This is intentional — feature gates are the most comprehensive and serve as a safe default.
+
+**Key automated gates** (v1.9.2):
+- `integrationWiring` → calls `verifyWiring()` — checks created files are imported/used
+- `standardsCompliance` → calls `runTaskStandardsCheck()` — checks naming, security, decisions.md rules
+- `outstandingFindings` → reads `last-review.json` — blocks if unresolved critical/high findings exist
+- `preRelease` → verifies codebase is releasable (no outstanding findings + lint + typecheck)
+
+**CRITICAL**: No task type defaults to zero gates. Every task type MUST have at least `requestLogEntry` + `outstandingFindings`.
 
 **WebMCP** (optional): If `config.webmcp.enabled` and UI files changed, check tool coverage. Non-blocking.
 

package/.claude/docs/explore-agents.md

@@ -9,23 +9,43 @@ Launch as `Agent(subagent_type=Explore)`:
 ```
 Analyze the codebase for task: "[TASK_TITLE]"
 
-1. Use Glob to find files related to: [TASK_KEYWORDS]
-2. Use Grep to search for patterns, function names, component references
-3. Read app-map.md for existing components that could be reused
-4. Read function-map.md for existing utility functions that could be reused
-5. Read api-map.md for existing API endpoints that could be reused
-6. Read decisions.md for patterns that must be followed
-7. Map dependencies:
-   - Files that REFERENCE the target code
-   - Files REFERENCED BY the target code
-8. Surface assumptions that need verification
+STEP 1 — Domain-keyword search (MANDATORY, do this FIRST):
+  a. Extract 3-5 domain keywords from the task title
+     Example: "AI Policies tab" → ["policy", "policies", "automation", "AI"]
+     Example: "Payment service refactor" → ["payment", "checkout", "billing", "transaction"]
+  b. For EACH keyword, run:
+     - Glob **/*[keyword]* to find files with that keyword in the name
+     - Grep for the keyword in src/ (or project root) to find references in code
+  c. Read EVERY file that matches — these are potential reuse candidates
+  d. Pay special attention to files in shared/, utils/, lib/, common/ directories
+
+STEP 2 — Registry check (read ALL registry maps):
+  a. Read app-map.md for existing components that could be reused
+  b. Read function-map.md for existing utility functions
+  c. Read api-map.md for existing API endpoints
+  d. Read any other *-map.md files in .workflow/state/
+  e. For each planned NEW item, check if something similar already exists
+
+STEP 3 — Pattern & dependency analysis:
+  a. Read decisions.md for patterns that must be followed
+  b. Map dependencies:
+     - Files that REFERENCE the target code
+     - Files REFERENCED BY the target code
+  c. Surface assumptions that need verification
 
 Return a structured summary:
+- **REUSE CANDIDATES** (MUST be first section):
+  List every existing file/component/function/service that overlaps
+  with what this task plans to create. For each: path, purpose, and
+  whether the task should USE it, EXTEND it, or CREATE new.
 - Related files (path + why it's relevant)
-- Existing components to reuse
-- Patterns to follow
+- Patterns to follow (from decisions.md)
 - Dependency map
 - Assumptions to verify
+
+CRITICAL: If domain-keyword search finds existing implementations that
+overlap with the task's goals, this MUST be prominently flagged.
+Do NOT skip Step 1 even if you think you already know the codebase.
 ```
 
 ## Agent 2: Best Practices Researcher

package/.claude/rules/operations/github-releases.md

@@ -13,9 +13,23 @@ globs: package.json
 
 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
 

package/lib/installer.js

@@ -1115,8 +1115,12 @@ function createWorkflowStructure(projectRoot, config) {
   // (which use require/module.exports) crash with "require is not defined".
   // Same pattern as scripts/package.json.
   const workflowPkgPath = path.join(workflowDir, 'package.json');
-  if (!fs.existsSync(workflowPkgPath)) {
-    fs.writeFileSync(workflowPkgPath, JSON.stringify({ type: 'commonjs' }, null, 2) + '\n');
+  try {
+    fs.writeFileSync(workflowPkgPath, JSON.stringify({ type: 'commonjs' }, null, 2) + '\n', { flag: 'wx' });
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      throw err;
+    }
   }
 
   // Create config.json using shared defaults with project-specific overrides

package/package.json

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

package/scripts/flow-community.js

@@ -257,18 +257,30 @@ function collectShareableData(config) {
 
 /**
  * Get WogiFlow version from package.json.
+ * Uses require.resolve to find the actual wogiflow package, not the host project.
  * @returns {string}
  */
 let _cachedVersion = null;
 function getWogiFlowVersion() {
   if (_cachedVersion) return _cachedVersion;
   try {
-    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkgPath = require.resolve('wogiflow/package.json');
     const pkg = safeJsonParse(pkgPath, {});
     _cachedVersion = pkg.version || 'unknown';
     return _cachedVersion;
   } catch {
-    _cachedVersion = 'unknown';
+    // Fallback: resolve relative to this file (works when running from source repo)
+    try {
+      const fallbackPath = path.join(__dirname, '..', 'package.json');
+      const pkg = safeJsonParse(fallbackPath, {});
+      if (pkg.name === 'wogiflow') {
+        _cachedVersion = pkg.version || 'unknown';
+      } else {
+        _cachedVersion = 'unknown';
+      }
+    } catch {
+      _cachedVersion = 'unknown';
+    }
     return _cachedVersion;
   }
 }