wogiflow 1.9.5 → 1.9.7

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

@@ -701,7 +701,7 @@ Display:
     for (const reqs of [featureReqs, bugfixReqs, refactorReqs]) {
       reqs.push('requestLogEntry');
     }
-    featureReqs.push('appMapUpdate');
+    featureReqs.push('registryUpdate');
 
     config.qualityGates = {
       feature: { require: featureReqs },

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

@@ -25,6 +25,46 @@ This command is **automatically triggered** (when strict mode is enabled) for:
 5. **Integration Questions**: "How to integrate X with Y?"
 6. **Comparison Questions**: "What can we learn from X?", "How does X compare to Y?"
 
+## Step 0: Config Loading (MANDATORY — before all phases)
+
+Before ANY research phase, read the project's config to determine depth, format, and verification requirements:
+
+```bash
+cat .workflow/config.json | grep -A 30 '"research"'
+```
+
+**Extract and apply these settings:**
+
+1. **Determine depth** (in priority order):
+   - CLI flag (`--deep`, `--quick`, etc.) → use that depth
+   - If auto-triggered (no flag): classify question type and look up `research.triggers`:
+     - Capability question ("Does X support Y?") → `triggers.capabilityQuestions` (default: `"standard"`)
+     - Feasibility question ("Is it possible to...") → `triggers.feasibilityQuestions` (default: `"deep"`)
+     - Existence question ("Is there a...") → `triggers.existenceQuestions` (default: `"standard"`)
+     - Architecture question ("How does X work?") → `triggers.architectureQuestions` (default: `"deep"`)
+     - Integration question ("How to integrate X with Y?") → `triggers.integrationQuestions` (default: `"deep"`)
+     - Comparison question ("How does X compare to Y?") → `triggers.comparisonQuestions` (default: `"deep"`)
+   - Fallback: `research.defaultDepth` (default: `"standard"`)
+
+2. **Apply format flags** from config:
+   - `requireVerificationFormat: true` → ALL assumptions must have `[VERIFIED]`/`[UNVERIFIED]` markers
+   - `requireCitations: true` → ALL claims must have an Evidence Chain entry
+   - `assumptionTracking: true` → Assumption Stack table is MANDATORY in output
+   - `negativeEvidenceRule: true` → Negative claims require exhaustive search evidence
+
+3. **Display header block** (MANDATORY):
+   ```markdown
+   ## Research Report
+   **Question:** [the question]
+   **Depth:** [resolved depth from step 1]
+   **Flow:** [Standard/Comparison]
+   **Config applied:** requireVerification=[yes/no], citations=[yes/no], assumptionTracking=[yes/no]
+   ```
+
+**If config.json has no `research` section or is unreadable**: use defaults (depth: standard, all format flags: true).
+
+---
+
 ## Research Protocol Phases
 
 There are two flows depending on question type:
@@ -199,6 +239,7 @@ In `.workflow/config.json`:
     "enabled": true,
     "defaultDepth": "standard",
     "autoTrigger": true,
+    "requireVerificationFormat": true,
     "maxTokensPerDepth": {
       "quick": 5000,
       "standard": 20000,
@@ -210,7 +251,15 @@ In `.workflow/config.json`:
     "cacheExpiryHours": 24,
     "budgetMode": "soft",
     "negativeEvidenceRule": true,
-    "assumptionTracking": true
+    "assumptionTracking": true,
+    "triggers": {
+      "capabilityQuestions": "standard",
+      "feasibilityQuestions": "deep",
+      "existenceQuestions": "standard",
+      "architectureQuestions": "deep",
+      "integrationQuestions": "deep",
+      "comparisonQuestions": "deep"
+    }
   }
 }
 ```
@@ -269,6 +318,26 @@ When `research.requireCitations` is enabled and `research.autoTrigger` is true:
 - Claims without citations are flagged
 - Negative claims require exhaustive search evidence
 
+## Output Checklist (MANDATORY — self-verify before presenting)
+
+Before presenting ANY research report, verify ALL of these are present. If any is missing, add it before outputting.
+
+| # | Check | Required When |
+|---|-------|---------------|
+| 1 | **Header block** with Question, Depth, Flow, Config applied | Always |
+| 2 | **Conclusion** section with direct answer | Always |
+| 3 | **Assumption Stack** table with `[VERIFIED]`/`[UNVERIFIED]` markers | `assumptionTracking: true` (default) |
+| 4 | **Evidence Chain** table with Claim, Source Type, Source Location, Confidence | `requireCitations: true` (default) |
+| 5 | **Confidence level** (HIGH/MEDIUM/LOW) | Always |
+| 6 | **Searches Performed** list (web + local) | Always |
+| 7 | **Negative Evidence format** for any "X doesn't exist" claims | `negativeEvidenceRule: true` (default) |
+| 8 | **Comparison table** (External Feature / Local Equivalent / Status) | Comparison flow only |
+| 9 | **Recommendation Verification** (EXISTS/PARTIAL/MISSING markers) | Comparison flow only |
+
+**Self-check prompt**: "Have I included all mandatory sections per config? Is every assumption marked? Is every claim cited?"
+
+If the report is missing any required section, DO NOT present it — add the missing section first.
+
 ## CLI Compatibility
 
 This command currently supports Claude Code only.

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

@@ -302,7 +302,7 @@ If violations found: fix, re-run, only proceed when all pass. Violations auto-re
 **First**: Run `node node_modules/wogiflow/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. Gates are type-specific:
-- **feature**: loopComplete, tests, appMapUpdate, requestLogEntry, integrationWiring, standardsCompliance
+- **feature**: loopComplete, tests, registryUpdate, requestLogEntry, integrationWiring, standardsCompliance
 - **bugfix**: loopComplete, tests, requestLogEntry, standardsCompliance, learningEnforcement
 - **refactor**: loopComplete, tests, noNewFeatures, smokeTest, standardsCompliance
 - **chore**: requestLogEntry, outstandingFindings
@@ -311,7 +311,8 @@ If violations found: fix, re-run, only proceed when all pass. Violations auto-re
 
 **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):
+**Key automated gates** (v1.9.7):
+- `registryUpdate` → runs `flow registry-manager scan` on ALL active registries (app-map, function-map, api-map, schema-map, service-map). Auto-updates maps when new entries found. Replaces old `appMapUpdate` no-op gate.
 - `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
@@ -328,7 +329,7 @@ Reflection: "Have I introduced any bugs or regressions?"
 1. Reflection: "Does this match what the user asked for?"
 2. Close out all TodoWrite items for this task
 3. Move task to recentlyCompleted in ready.json
-4. Update request-log.md, app-map.md, function-map.md, api-map.md as needed
+4. Registry maps auto-updated by `registryUpdate` quality gate (runs `flow registry-manager scan` on all active registries — app-map, function-map, api-map, schema-map, service-map)
 5. If `config.webmcp.enabled` and UI files created: run `node node_modules/wogiflow/scripts/flow-webmcp-generator.js scan`
 6. Commit: `feat: Complete wf-XXXXXXXX - [title]`
 7. Show completion summary

package/.claude/docs/config-reference.md

@@ -163,7 +163,7 @@ Customize which checks are required per task type.
 {
   "qualityGates": {
     "feature": {
-      "require": ["loopComplete", "tests", "appMapUpdate", "requestLogEntry"],
+      "require": ["loopComplete", "tests", "registryUpdate", "requestLogEntry"],
       "optional": ["review"]
     },
     "bugfix": {
@@ -174,7 +174,7 @@ Customize which checks are required per task type.
 }
 ```
 
-**Available gates**: `loopComplete`, `tests`, `generatedTestsPass`, `uiVerification`, `apiVerification`, `appMapUpdate`, `requestLogEntry`, `integrationWiring`, `standardsCompliance`, `outstandingFindings`, `preRelease`, `noNewFeatures`, `smokeTest`, `learningEnforcement`, `review`, `docs`, `webmcpVerification`
+**Available gates**: `loopComplete`, `tests`, `generatedTestsPass`, `uiVerification`, `apiVerification`, `registryUpdate`, `requestLogEntry`, `integrationWiring`, `standardsCompliance`, `outstandingFindings`, `preRelease`, `noNewFeatures`, `smokeTest`, `learningEnforcement`, `review`, `docs`, `webmcpVerification`
 
 **Task types**: `feature`, `bugfix`, `refactor`, `chore`, `release`, `fix`
 

package/.claude/docs/knowledge-base/02-task-execution/03-verification.md

@@ -62,7 +62,7 @@ Quality gates are requirements that must pass before a task can be completed.
 {
   "qualityGates": {
     "feature": {
-      "require": ["tests", "appMapUpdate", "requestLogEntry"],
+      "require": ["tests", "registryUpdate", "requestLogEntry"],
       "optional": ["review", "docs"]
     },
     "bugfix": {
@@ -84,7 +84,7 @@ Quality gates are requirements that must pass before a task can be completed.
 | `tests` | npm test passes |
 | `lint` | npm run lint passes (with auto-fix) |
 | `typecheck` | npm run typecheck passes |
-| `appMapUpdate` | New components added to app-map.md |
+| `registryUpdate` | All registry maps (app-map, function-map, api-map, schema-map, service-map) auto-scanned |
 | `requestLogEntry` | Task logged in request-log.md |
 | `noNewFeatures` | (Refactor) No new functionality added |
 | `integrationWiring` | Created files are imported/used somewhere (not orphaned) |
@@ -134,7 +134,7 @@ Running quality gates...
   ✓ lint passed (auto-fixed)
   ✓ typecheck passed
   ✓ requestLogEntry (found in request-log)
-  ○ appMapUpdate (verify manually if components created)
+  ✓ registryUpdate (auto-scanned: app-map.md updated)
 
 All gates passed!
 ```

package/.claude/docs/knowledge-base/02-task-execution/05-session-review.md

@@ -196,7 +196,7 @@ Session review can be added to quality gates:
 {
   "qualityGates": {
     "feature": {
-      "require": ["tests", "sessionReview", "appMapUpdate"]
+      "require": ["tests", "sessionReview", "registryUpdate"]
     }
   }
 }

package/.claude/docs/knowledge-base/02-task-execution/README.md

@@ -122,7 +122,7 @@ Comprehensive code review before finalizing changes.
   },
   "qualityGates": {
     "feature": {
-      "require": ["tests", "appMapUpdate", "requestLogEntry"]
+      "require": ["tests", "registryUpdate", "requestLogEntry"]
     }
   }
 }

package/.claude/docs/knowledge-base/02-task-execution/trade-offs.md

@@ -141,7 +141,7 @@ Every configuration decision in WogiFlow involves trade-offs. Understanding thes
 {
   "qualityGates": {
     "feature": {
-      "require": ["tests", "lint", "typecheck", "appMapUpdate", "requestLogEntry", "review"]
+      "require": ["tests", "lint", "typecheck", "registryUpdate", "requestLogEntry", "review"]
     }
   }
 }

package/.claude/docs/knowledge-base/configuration/README.md

@@ -127,7 +127,7 @@ cat .workflow/config.json
   },
   "qualityGates": {
     "feature": {
-      "require": ["tests", "appMapUpdate", "requestLogEntry", "review"]
+      "require": ["tests", "registryUpdate", "requestLogEntry", "review"]
     }
   }
 }

package/.claude/docs/knowledge-base/configuration/all-options.md

@@ -410,7 +410,7 @@ Per-task-type quality requirements that must pass before task completion.
   "qualityGates": {
     "preTaskBaseline": { "enabled": false },
     "feature": {
-      "require": ["loopComplete", "tests", "appMapUpdate", "requestLogEntry", "integrationWiring", "standardsCompliance"],
+      "require": ["loopComplete", "tests", "registryUpdate", "requestLogEntry", "integrationWiring", "standardsCompliance"],
       "optional": ["review", "docs", "webmcpVerification"]
     },
     "bugfix": {
@@ -433,7 +433,7 @@ Per-task-type quality requirements that must pass before task completion.
 | `qualityGates.bugfix.require` | string[] | See above | Required gates for bugfix tasks |
 | `qualityGates.refactor.require` | string[] | See above | Required gates for refactor tasks |
 
-Available gate values: `loopComplete`, `tests`, `appMapUpdate`, `requestLogEntry`, `integrationWiring`, `standardsCompliance`, `learningEnforcement`, `resolutionPopulated`, `noNewFeatures`, `smokeTest`, `review`, `docs`, `webmcpVerification`.
+Available gate values: `loopComplete`, `tests`, `registryUpdate`, `requestLogEntry`, `integrationWiring`, `standardsCompliance`, `learningEnforcement`, `resolutionPopulated`, `noNewFeatures`, `smokeTest`, `review`, `docs`, `webmcpVerification`.
 
 ---
 

package/.workflow/templates/claude-md.hbs

@@ -210,12 +210,9 @@ When creating tasks programmatically, always call `generateTaskId(title)` — ne
 
 ### After Completing:
 1. Update `request-log.md` with tags
-2. Update `app-map.md` if components created/deleted/renamed
-3. Update `function-map.md` if utilities created/deleted/renamed — run `npx flow function-index scan`
-4. Update `api-map.md` if endpoints created/deleted/renamed — run `npx flow api-index scan`
-5. Update other active registry maps if relevant — run `npx flow registry-manager scan`
-6. Run quality gates (lint, typecheck, test)
-7. Provide completion report
+2. Registry maps (app-map, function-map, api-map, schema-map, service-map) are **auto-updated** by the `registryUpdate` quality gate — it runs `flow registry-manager scan` on all active registries
+3. Run quality gates (lint, typecheck, test)
+4. Provide completion report
 
 ## Auto-Validation (CRITICAL)
 

package/package.json

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

package/scripts/flow-config-defaults.js

@@ -302,7 +302,7 @@ const CONFIG_DEFAULTS = {
   qualityGates: {
     preTaskBaseline: { enabled: false },
     feature: {
-      require: ['loopComplete', 'tests', 'generatedTestsPass', 'uiVerification', 'apiVerification', 'appMapUpdate', 'requestLogEntry', 'integrationWiring', 'standardsCompliance'],
+      require: ['loopComplete', 'tests', 'generatedTestsPass', 'uiVerification', 'apiVerification', 'registryUpdate', 'requestLogEntry', 'integrationWiring', 'standardsCompliance'],
       optional: ['review', 'docs', 'webmcpVerification']
     },
     bugfix: {

package/scripts/flow-done

@@ -76,8 +76,8 @@ for gate in gates:
         except:
             print('  \033[0;33m○\033[0m requestLogEntry (verify manually)')
 
-    elif gate == 'appMapUpdate':
-        print('  \033[0;33m○\033[0m appMapUpdate (verify manually if components created)')
+    elif gate == 'appMapUpdate' or gate == 'registryUpdate':
+        print('  \033[0;33m○\033[0m registryUpdate (verify manually if components created)')
 
     else:
         print(f'  \033[0;33m○\033[0m {gate} (manual check)')

package/scripts/flow-done.js

@@ -121,6 +121,20 @@ try {
 // v5.2 verification profiles
 const { loadProfile: loadVerificationProfile } = require('./flow-verification-profile');
 
+// v1.9.7 registry map update gate — lazy-loaded to avoid startup cost
+// Loaded inside the registryUpdate gate branch only
+let _registryManagerModule = undefined; // undefined = not yet loaded, null = load failed
+function getRegistryManager() {
+  if (_registryManagerModule === undefined) {
+    try {
+      _registryManagerModule = require('./flow-registry-manager');
+    } catch (err) {
+      _registryManagerModule = null;
+    }
+  }
+  return _registryManagerModule;
+}
+
 // Path for last failure artifact
 const LAST_FAILURE_PATH = path.join(PATHS.state, 'last-failure.json');
 
@@ -338,8 +352,111 @@ function runQualityGates(taskId, taskType) {
         if (process.env.DEBUG) console.error(`[DEBUG] requestLogEntry check: ${err.message}`);
         console.log(`  ${color('yellow', '○')} requestLogEntry (could not check)`);
       }
-    } else if (gate === 'appMapUpdate') {
-      console.log(`  ${color('yellow', '○')} appMapUpdate (verify manually if components created)`);
+    } else if (gate === 'appMapUpdate' || gate === 'registryUpdate') {
+      // v1.9.7: Programmatic registry scan — replaces manual "verify manually" no-op.
+      // Runs flow-registry-manager scan on all active registries, comparing modified files
+      // against registry entries to detect missing registrations.
+      // v1.9.8: Deprecation warning for old gate name
+      if (gate === 'appMapUpdate') {
+        console.log(`  ${color('yellow', '⚠')} appMapUpdate is deprecated — update config.json qualityGates to use 'registryUpdate'`);
+      }
+      const registryMod = getRegistryManager();
+      if (registryMod) {
+        try {
+          console.log('  Running registry update check...');
+          const modifiedFiles = getModifiedFiles();
+
+          // Get map file timestamps BEFORE scan (to detect changes)
+          const mapFiles = ['app-map.md', 'function-map.md', 'api-map.md', 'schema-map.md', 'service-map.md'];
+          const beforeHashes = {};
+          for (const mf of mapFiles) {
+            const mapPath = path.join(PATHS.state, mf);
+            try {
+              beforeHashes[mf] = fs.existsSync(mapPath) ? fs.statSync(mapPath).mtimeMs : 0;
+            } catch (err) {
+              beforeHashes[mf] = 0;
+            }
+          }
+
+          // Detect active plugins to check if scan is needed (lightweight, no async)
+          const { RegistryManager } = registryMod;
+          const manager = new RegistryManager();
+          manager.loadPlugins();
+          manager.detectStack();
+          manager.activatePlugins();
+
+          // Only scan if there are active plugins
+          if (manager.activePlugins.length > 0) {
+            // scanAll is async but we need sync behavior in quality gates
+            // Use spawnSync to run the scan as a child process
+            // v1.9.8: Added cwd, write JSON to stderr to avoid stdout pollution from require() side-effects
+            const scanResult = spawnSync('node', [
+              '-e',
+              `const {RegistryManager} = require(${JSON.stringify(path.join(__dirname, 'flow-registry-manager'))});
+              const m = new RegistryManager(); m.loadPlugins(); m.detectStack(); m.activatePlugins();
+              m.scanAll().then(r => { process.stderr.write('SCAN_RESULT:' + JSON.stringify(r)); process.exit(0); })
+              .catch(err => { process.stderr.write('SCAN_RESULT:' + JSON.stringify({error: err.message})); process.exit(1); });`
+            ], {
+              encoding: 'utf-8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+              timeout: 30000,
+              cwd: process.cwd()
+            });
+
+            if (scanResult.status === 0) {
+              // Extract scan result from stderr (after SCAN_RESULT: marker) to avoid stdout pollution
+              const stderrOutput = scanResult.stderr || '';
+              const markerIdx = stderrOutput.indexOf('SCAN_RESULT:');
+              const jsonStr = markerIdx >= 0 ? stderrOutput.slice(markerIdx + 'SCAN_RESULT:'.length) : '{}';
+              const results = safeJsonParseString(jsonStr, {});
+
+              // Check which map files were updated
+              const updatedMaps = [];
+              for (const mf of mapFiles) {
+                const mapPath = path.join(PATHS.state, mf);
+                try {
+                  const afterMtime = fs.existsSync(mapPath) ? fs.statSync(mapPath).mtimeMs : 0;
+                  if (afterMtime > beforeHashes[mf]) {
+                    updatedMaps.push(mf);
+                  }
+                } catch (err) {
+                  // ignore
+                }
+              }
+
+              // Check if modified files include patterns that should be in registries
+              const relevantExtensions = ['.js', '.ts', '.jsx', '.tsx', '.vue', '.svelte'];
+              const codeFiles = modifiedFiles.filter(f => relevantExtensions.some(ext => f.endsWith(ext)));
+              const nonTestFiles = codeFiles.filter(f => !f.includes('test') && !f.includes('spec') && !f.includes('__test'));
+
+              const activeIds = manager.activePlugins.map(p => p.constructor.id);
+              const scanSummary = Object.entries(results)
+                .filter(([id, r]) => r.success && !r.empty)
+                .map(([id]) => id);
+
+              if (updatedMaps.length > 0) {
+                console.log(`  ${color('green', '✓')} registryUpdate (auto-scanned: ${updatedMaps.join(', ')} updated)`);
+              } else if (scanSummary.length > 0) {
+                console.log(`  ${color('green', '✓')} registryUpdate (scanned ${activeIds.join(', ')} — maps already current)`);
+              } else if (nonTestFiles.length === 0) {
+                console.log(`  ${color('green', '✓')} registryUpdate (no registrable code files modified)`);
+              } else {
+                console.log(`  ${color('green', '✓')} registryUpdate (scanned — no new entries found)`);
+              }
+            } else {
+              console.log(`  ${color('yellow', '⚠')} registryUpdate (scan error — degraded to manual check)`);
+              if (process.env.DEBUG) console.error(`[DEBUG] registry scan stderr: ${scanResult.stderr}`);
+            }
+          } else {
+            console.log(`  ${color('green', '✓')} registryUpdate (no active registry plugins)`);
+          }
+        } catch (err) {
+          // Graceful degradation — don't block task completion on scan errors
+          console.log(`  ${color('yellow', '⚠')} registryUpdate (error: ${truncateOutput(err.message, 3, 200)} — verify manually)`);
+        }
+      } else {
+        console.log(`  ${color('yellow', '⚠')} registryUpdate (registry manager not available — verify manually)`);
+      }
     } else if (gate === 'loopComplete') {
       // v2.1: Explicit loop completion check
       const activeLoop = getActiveLoop();

package/scripts/flow-version-check.js

@@ -1,12 +1,16 @@
 /**
  * flow-version-check.js
  *
- * Proactive Claude Code version compatibility check.
- * Called at session start, but only checks once per install/update
- * to avoid nagging on every session.
+ * Version compatibility and update checks.
+ * Called at session start with two independent checks:
  *
- * - Hard minimum (2.1.23): Hooks don't work below this — always warn
- * - Soft gates (2.1.50+, 2.1.72+): Degrade gracefully, no warning
+ * 1. Claude Code compatibility: checks once per install/update
+ *    - Hard minimum (2.1.23): Hooks don't work below this — always warn
+ *    - Soft gates (2.1.50+, 2.1.72+): Degrade gracefully, no warning
+ *
+ * 2. WogiFlow npm update: checks once per 24h
+ *    - Fetches latest version from npm registry
+ *    - Warns if local version is outdated
  */
 
 const fs = require('fs');
@@ -135,4 +139,107 @@ function checkClaudeCodeVersionOnce() {
   return null;
 }
 
-module.exports = { checkClaudeCodeVersionOnce, getClaudeCodeVersion };
+// --- WogiFlow npm update check ---
+
+const UPDATE_CHECK_PATH = path.join(PATHS.state, '.update-check.json');
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Get the installed WogiFlow version from package.json.
+ * @returns {string} Version string or 'unknown'
+ */
+function getLocalWogiFlowVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || 'unknown';
+  } catch (err) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Fetch the latest WogiFlow version from the npm registry.
+ * Uses a short timeout to avoid blocking session start.
+ * @returns {string|null} Latest version or null on failure
+ */
+function fetchLatestNpmVersion() {
+  try {
+    const output = execSync(
+      'npm view wogiflow version 2>/dev/null || echo ""',
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000 }
+    ).trim();
+    const match = output.match(/^(\d+\.\d+\.\d+)$/);
+    return match ? match[1] : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings. Returns true if remote is newer than local.
+ * @param {string} local - e.g. "1.9.4"
+ * @param {string} remote - e.g. "1.9.5"
+ * @returns {boolean}
+ */
+function isNewerVersion(local, remote) {
+  const [lMaj, lMin, lPat] = local.split('.').map(Number);
+  const [rMaj, rMin, rPat] = remote.split('.').map(Number);
+  if (rMaj !== lMaj) return rMaj > lMaj;
+  if (rMin !== lMin) return rMin > lMin;
+  return rPat > lPat;
+}
+
+/**
+ * Check if a newer WogiFlow version is available on npm.
+ * Checks at most once per 24 hours to avoid unnecessary network calls.
+ *
+ * @returns {string|null} Warning message if outdated, null otherwise
+ */
+function checkWogiFlowUpdateOnce() {
+  const localVersion = getLocalWogiFlowVersion();
+  if (localVersion === 'unknown') return null;
+
+  // Check cached result
+  try {
+    const cached = fs.readFileSync(UPDATE_CHECK_PATH, 'utf-8');
+    const data = JSON.parse(cached);
+    const age = Date.now() - new Date(data.checkedAt).getTime();
+    if (age < UPDATE_CHECK_TTL_MS && data.localVersion === localVersion) {
+      // Still within TTL and same local version — return cached result
+      if (data.latestVersion && isNewerVersion(localVersion, data.latestVersion)) {
+        return `WogiFlow ${localVersion} is outdated. Latest: ${data.latestVersion}. Update with: npm install -D wogiflow@latest`;
+      }
+      return null;
+    }
+  } catch (err) {
+    // No cache or invalid — proceed with fresh check
+  }
+
+  // Fetch from npm
+  const latestVersion = fetchLatestNpmVersion();
+
+  // Cache the result (even if null — prevents retrying on every session)
+  try {
+    fs.mkdirSync(path.dirname(UPDATE_CHECK_PATH), { recursive: true });
+    fs.writeFileSync(UPDATE_CHECK_PATH, JSON.stringify({
+      localVersion,
+      latestVersion: latestVersion || null,
+      checkedAt: new Date().toISOString()
+    }, null, 2));
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[version-check] Failed to cache update check: ${err.message}`);
+    }
+  }
+
+  if (!latestVersion) return null;
+
+  if (isNewerVersion(localVersion, latestVersion)) {
+    return `WogiFlow ${localVersion} is outdated. Latest: ${latestVersion}. Update with: npm install -D wogiflow@latest`;
+  }
+
+  return null;
+}
+
+module.exports = { checkClaudeCodeVersionOnce, getClaudeCodeVersion, checkWogiFlowUpdateOnce };

package/scripts/hooks/entry/claude-code/pre-tool-use.js

@@ -213,8 +213,35 @@ async function main() {
     // v7.0: Subagents exempt — spawned by main agent which already went through routing.
     // v7.1: Defense-in-depth — only bypass when an active task exists.
     // v8.0: Added Agent, WebSearch, WebFetch to close bypass vectors.
+    // v8.1: Whitelist read-only git commands — Claude naturally runs git status/log/diff
+    //        to gather context before routing. These are pure reads with no side effects.
     const skipRoutingGateForSubagent = isSubagent && hasActiveTask();
-    if (!skipRoutingGateForSubagent && (toolName === 'Bash' || toolName === 'EnterPlanMode' || toolName === 'Read' || toolName === 'Glob' || toolName === 'Grep' || toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit' || toolName === 'Agent' || toolName === 'WebSearch' || toolName === 'WebFetch')) {
+
+    // Read-only git commands whitelist — allowed before routing.
+    // These are pure read operations that cannot bypass task tracking.
+    // Safety: reject commands with shell chaining operators to prevent abuse.
+    let skipRoutingGateForReadOnlyGit = false;
+    if (toolName === 'Bash' && toolInput.command) {
+      const cmd = toolInput.command.trim();
+      const READ_ONLY_GIT_PREFIXES = [
+        'git status', 'git log', 'git diff', 'git branch',
+        'git show', 'git rev-parse', 'git remote -v', 'git tag -l',
+        'git ls-files', 'git describe'
+      ];
+      // Block shell chaining operators AND control characters that could bypass prefix matching
+      const SHELL_CHAIN_OPERATORS = /[;&|`$()\n\r\\]/;
+      // Block destructive flags that could appear after an otherwise-safe prefix
+      const DESTRUCTIVE_GIT_FLAGS = /\s-[dD]\b|\s--delete\b|\s--force\b|\s--hard\b|\s--prune\b/;
+      if (
+        READ_ONLY_GIT_PREFIXES.some(prefix => cmd.startsWith(prefix)) &&
+        !SHELL_CHAIN_OPERATORS.test(cmd) &&
+        !DESTRUCTIVE_GIT_FLAGS.test(cmd)
+      ) {
+        skipRoutingGateForReadOnlyGit = true;
+      }
+    }
+
+    if (!skipRoutingGateForSubagent && !skipRoutingGateForReadOnlyGit && (toolName === 'Bash' || toolName === 'EnterPlanMode' || toolName === 'Read' || toolName === 'Glob' || toolName === 'Grep' || toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit' || toolName === 'Agent' || toolName === 'WebSearch' || toolName === 'WebFetch')) {
       try {
         const routingResult = checkRoutingGate(toolName, config);
         if (routingResult.blocked) {

package/scripts/hooks/entry/claude-code/session-start.js

@@ -82,12 +82,15 @@ async function main() {
       }
     }
 
-    // --- Version compatibility check (runs once per install/update) ---
-    // Only warns if Claude Code is below the hard minimum (2.1.23) where hooks don't work.
+    // --- Version compatibility checks ---
+    // 1. Claude Code: warns if below hard minimum (2.1.23) where hooks don't work
+    // 2. WogiFlow npm: warns if a newer version is available (checks once per 24h)
     let versionWarning = null;
+    let updateWarning = null;
     try {
-      const { checkClaudeCodeVersionOnce } = require('../../../flow-version-check');
+      const { checkClaudeCodeVersionOnce, checkWogiFlowUpdateOnce } = require('../../../flow-version-check');
       versionWarning = checkClaudeCodeVersionOnce();
+      updateWarning = checkWogiFlowUpdateOnce();
     } catch (err) {
       if (process.env.DEBUG) {
         console.error(`[session-start] Version check failed: ${err.message}`);
@@ -285,6 +288,11 @@ async function main() {
       coreResult.context.versionWarning = versionWarning;
     }
 
+    // Inject WogiFlow update warning (if any)
+    if (updateWarning && coreResult && coreResult.context) {
+      coreResult.context.updateWarning = updateWarning;
+    }
+
     // Inject drift detection results (if any)
     if (driftDetected && coreResult && coreResult.context) {
       if (driftMarkerMissing) {