wogiflow 2.4.1 → 2.4.3

package/.claude/docs/claude-code-compatibility.md

@@ -70,6 +70,7 @@ flow parallel check  # See available parallel tasks
 | 1.9.5+ | 2.1.74+ | SessionEnd timeout fix, managed policy ask rules, autoMemoryDirectory, Agent tool routing gate fix |
 | 2.0.0+ | 2.1.76+ | PostCompact hook, Elicitation/ElicitationResult events, deferred tool schema fix |
 | 2.1.0+ | 2.1.77+ | PreToolUse allow/deny separation, 128k output tokens, worktree sparse checkout, compaction circuit breaker |
+| 2.4.0+ | 2.1.83+ | managed-settings.d/, CwdChanged/FileChanged hooks, ENV_SCRUB, --channels limitations, MEMORY.md 25KB cap |
 
 ### Environment Variables (2.1.19+)
 
@@ -236,6 +237,32 @@ await cancelTask('wf-123', 'superseded', false);
 - **Memory growth fix**: Fixed progress messages surviving compaction in long-running sessions. Reduces memory pressure during long WogiFlow bulk-loop sessions.
 - **Faster startup on macOS**: ~60ms faster by reading keychain credentials in parallel. Faster `--resume` on fork-heavy sessions — up to 45% faster loading and ~100-150MB less peak memory. Benefits WogiFlow sessions with heavy hook context.
 
+### Features in 2.1.83+
+
+- **managed-settings.d/ drop-in directory**: A `managed-settings.d/` directory alongside `managed-settings.json` allows separate teams/tools to deploy independent policy fragments that merge alphabetically. WogiFlow currently generates `settings.local.json` — for wogiflow-cloud teams, this opens the door to deploying team policies as individual fragments (e.g., `00-wogiflow-hooks.json`, `50-team-policy.json`). No code change needed yet; tracked as cloud opportunity.
+
+- **CwdChanged and FileChanged hook events**: Two new hook events. `CwdChanged` fires when the working directory changes (useful for direnv-style setups). `FileChanged` fires when watched files change on disk — WogiFlow could use this to detect external changes to `.workflow/state/` files and auto-rescan. Added to `UNUSED_SUPPORTED_EVENTS` in `claude-code.js`. Implementation deferred to a future task.
+
+- **CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1**: Strips Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). **Impact on WogiFlow**: Hooks are subprocesses, so any hook that needs API keys (e.g., `flow-correction-detector.js` spawning a child process for async correction detection) will not have credentials available. The correction detector now gracefully degrades (returns `isCorrection: false`) when no API key is available. `flow-providers.js` makes direct `https.request()` calls from the hook process itself (not a subprocess of the subprocess), so it reads `process.env` before scrubbing — but if ENV_SCRUB applies transitively to hook processes, provider calls would also be affected. For wogiflow-cloud: if cloud sync hooks need API keys, they must use an alternative credential mechanism (file-based, keychain, or passed via hook input JSON).
+
+- **Agents can declare initialPrompt in frontmatter**: Agents can now auto-submit a first turn without the AI composing it. WogiFlow's 11 persona agents in `agents/` could use this for standardized opening probes. No code change needed; optimization opportunity.
+
+- **Background subagent fixes**: (1) Fixed subagents becoming invisible after context compaction — this prevented duplicate agent spawns in WogiFlow's parallel explore phase. (2) Fixed agents staying stuck in "running" state when git/API calls hang during cleanup. Both fixes improve reliability of `/wogi-start` explore phase and `/wogi-bulk-loop`.
+
+- **--channels disables AskUserQuestion and plan mode**: When `--channels` is active (remote/SDK), `AskUserQuestion` and plan-mode tools are disabled. **Impact on WogiFlow**: WogiFlow uses `AskUserQuestion` extensively for approval gates, clarifying questions, and interactive decisions. In `--channels` mode, these will silently fail or be unavailable. WogiFlow should detect channels mode and fall back to non-interactive patterns: auto-approve with defaults, skip clarifying questions, use best-effort decisions. Documented in CLAUDE.md template and wogi-start command.
+
+- **TaskOutput deprecated**: `TaskOutput` tool is deprecated in favor of using `Read` on the background task's output file path. WogiFlow does not use `TaskOutput` directly (confirmed by codebase search). No change needed.
+
+- **MEMORY.md index truncation**: Now truncates at **25KB** as well as 200 lines (previously only 200 lines). WogiFlow's MEMORY.md enforcement block at the top consumes space from this budget. Projects with large MEMORY.md files may lose entries silently. The CLAUDE.md template's auto-memory section already mentions 200 lines; the 25KB limit is enforced by Claude Code's system prompt and does not need to be duplicated in the template.
+
+- **Plugin manifest.userConfig**: Plugins can now prompt for configuration at enable time, with `sensitive: true` values stored in keychain (macOS) or protected credentials file. If WogiFlow becomes a Claude Code plugin, this provides native credential storage for cloud API tokens and model API keys — replacing `wogi login`'s file-based token storage. Tracked as cloud opportunity.
+
+- **WebFetch identifies as Claude-User**: `WebFetch` now sends a `Claude-User` user agent so site operators can recognize and allowlist/block Claude Code traffic via `robots.txt`. WogiFlow's explore agents (Agent 2: Best Practices, Agent 3: Version Verifier) use `WebFetch` for research. If sites block `Claude-User`, research agents will get empty results. Agents should treat unexpectedly empty WebFetch results as potentially blocked and log a warning.
+
+- **--mcp-config bypass fix**: Fixed `--mcp-config` CLI flag bypassing `allowedMcpServers`/`deniedMcpServers` managed policy enforcement. Security improvement — no WogiFlow code change needed.
+
+- **Uninstalled plugin hooks fix**: Fixed uninstalled plugin hooks continuing to fire until the next session. Improves hook hygiene for WogiFlow plugin management.
+
 ### Simple Mode Naming Distinction
 
 Claude Code's `CLAUDE_CODE_SIMPLE` environment variable (which enables a simplified tool set) is **unrelated** to WogiFlow's `loops.simpleMode` (a lightweight task completion loop using string detection). They are separate features that happen to share the word "simple":

package/.claude/settings.json

@@ -135,6 +135,6 @@
     ]
   },
   "_wogiFlowManaged": true,
-  "_wogiFlowVersion": "1.9.10",
+  "_wogiFlowVersion": "2.4.2",
   "_comment": "Shared WogiFlow hook configuration. Committed to repo for team use. User-specific overrides go in settings.local.json."
 }

package/.workflow/models/registry.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {
@@ -61,12 +61,12 @@
     "sql.js": "^1.14.1"
   },
   "optionalDependencies": {
-    "@babel/parser": "^7.29.0",
+    "@babel/parser": "^7.29.2",
     "@babel/traverse": "^7.29.0",
-    "@xenova/transformers": "^2.15.0"
+    "@huggingface/transformers": "^3.0.0"
   },
   "devDependencies": {
-    "eslint": "^9.0.0"
+    "eslint": "^10.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/MEMORY-ARCHITECTURE.md

@@ -88,7 +88,7 @@ flow knowledge-sync regenerate  # Regenerate stale files
 
 **Features**:
 - SQLite database using sql.js (pure JS)
-- Embedding generation via @xenova/transformers
+- Embedding generation via @huggingface/transformers
 - Semantic similarity search
 - Facts, proposals, and PRD chunk storage
 

package/scripts/base-workflow-step.js

@@ -0,0 +1,136 @@
+/**
+ * Wogi Flow - BaseWorkflowStep
+ *
+ * Base class for all flow-step-*.js workflow steps.
+ * Provides shared infrastructure: file filtering, context loading,
+ * validation, and result formatting.
+ *
+ * Subclasses override execute() with step-specific logic.
+ *
+ * Usage:
+ *   const { BaseWorkflowStep } = require('./base-workflow-step');
+ *
+ *   class MyStep extends BaseWorkflowStep {
+ *     constructor() {
+ *       super('myStep', {
+ *         extensions: ['.js', '.ts'],
+ *         excludeTests: true,
+ *         excludeDts: true,
+ *       });
+ *     }
+ *     async execute(files, options) {
+ *       // ... step-specific logic
+ *       return this.pass('All checks passed');
+ *     }
+ *   }
+ *
+ *   module.exports = { run: (options) => new MyStep().run(options) };
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { PATHS } = require('./flow-utils');
+
+class BaseWorkflowStep {
+  /**
+   * @param {string} name - Step identifier
+   * @param {object} [filterOpts] - File filtering options
+   * @param {string[]} [filterOpts.extensions] - File extensions to include (e.g., ['.js', '.ts'])
+   * @param {boolean} [filterOpts.excludeTests=true] - Exclude .test./.spec. files
+   * @param {boolean} [filterOpts.excludeDts=true] - Exclude .d.ts files
+   */
+  constructor(name, filterOpts = {}) {
+    this.name = name;
+    this.extensions = filterOpts.extensions ?? ['.js', '.ts', '.jsx', '.tsx'];
+    this.excludeTests = filterOpts.excludeTests ?? true;
+    this.excludeDts = filterOpts.excludeDts ?? true;
+  }
+
+  /**
+   * Main entry point — matches the `run(options)` interface expected by flow-workflow-steps.js
+   * @param {object} options
+   * @param {string[]} [options.files] - Files modified
+   * @param {object} [options.stepConfig] - Step configuration
+   * @param {string} [options.mode] - Step mode (block/warn/prompt/auto)
+   * @param {string} [options.taskType] - Task type
+   * @param {string} [options.taskId] - Task ID
+   * @param {string} [options.taskTitle] - Task title
+   * @returns {Promise<{passed: boolean, message: string, details?: any}>}
+   */
+  async run(options = {}) {
+    const { files = [], stepConfig = {}, ...rest } = options;
+
+    // Filter files to those this step cares about
+    const filteredFiles = this.filterFiles(files);
+
+    if (filteredFiles.length === 0) {
+      return this.pass(`No ${this.name}-eligible files modified`);
+    }
+
+    // Delegate to subclass
+    return await this.execute(filteredFiles, { stepConfig, ...rest });
+  }
+
+  /**
+   * Override in subclass — contains the step-specific logic.
+   * @param {string[]} files - Filtered files
+   * @param {object} options - Remaining options (stepConfig, mode, taskType, etc.)
+   * @returns {Promise<{passed: boolean, message: string, details?: any}>}
+   */
+  async execute(files, options) {
+    throw new Error(`${this.name}: execute() must be overridden`);
+  }
+
+  /**
+   * Filter files based on step's extension and exclusion rules.
+   * @param {string[]} files - Raw file list
+   * @returns {string[]} Filtered files
+   */
+  filterFiles(files) {
+    return files.filter(f => {
+      const hasExt = this.extensions.some(ext => f.endsWith(ext));
+      if (!hasExt) return false;
+      if (this.excludeTests && (f.includes('.test.') || f.includes('.spec.'))) return false;
+      if (this.excludeDts && f.endsWith('.d.ts')) return false;
+      return true;
+    });
+  }
+
+  /**
+   * Read a file safely, returning null on error.
+   * @param {string} relativePath - Path relative to project root
+   * @returns {string|null} File content or null
+   */
+  readFile(relativePath) {
+    const fullPath = path.join(PATHS.root, relativePath);
+    try {
+      if (!fs.existsSync(fullPath)) return null;
+      return fs.readFileSync(fullPath, 'utf8');
+    } catch (_err) {
+      return null;
+    }
+  }
+
+  /**
+   * Create a passing result.
+   * @param {string} message
+   * @returns {{passed: true, message: string}}
+   */
+  pass(message) {
+    return { passed: true, message };
+  }
+
+  /**
+   * Create a failing result.
+   * @param {string} message
+   * @param {any} [details]
+   * @returns {{passed: false, message: string, details?: any}}
+   */
+  fail(message, details) {
+    const result = { passed: false, message };
+    if (details !== undefined) result.details = details;
+    return result;
+  }
+}
+
+module.exports = { BaseWorkflowStep };

package/scripts/flow-adaptive-learning.js

@@ -15,7 +15,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
-const { getProjectRoot, colors } = require('./flow-utils');
+const { getProjectRoot, colors, PATHS } = require('./flow-utils');
 const { error: errorMsg } = require('./flow-output');
 const { readJson } = require('./flow-io');
 const { storeSingleLearning, getAdapterPath } = require('./flow-model-adapter');
@@ -26,9 +26,8 @@ const {
 } = require('./flow-failure-categories');
 const { validateRepoFormat, safeGitCommand, sanitizeCommitMessage } = require('./flow-security');
 
-const PROJECT_ROOT = getProjectRoot();
-const LEARNING_LOG_PATH = path.join(PROJECT_ROOT, '.workflow', 'state', 'adaptive-learning.json');
-const STRATEGY_STATS_PATH = path.join(PROJECT_ROOT, '.workflow', 'state', 'strategy-effectiveness.json');
+const LEARNING_LOG_PATH = path.join(PATHS.state, 'adaptive-learning.json');
+const STRATEGY_STATS_PATH = path.join(PATHS.state, 'strategy-effectiveness.json');
 
 // ============================================================
 // Failure Analysis
@@ -690,7 +689,7 @@ function exportLearningsForSharing() {
   }
 
   // Load model adapter files and extract learnings sections
-  const adaptersDir = path.join(PROJECT_ROOT, '.workflow', 'model-adapters');
+  const adaptersDir = PATHS.modelAdapters;
   if (fs.existsSync(adaptersDir)) {
     const adapterFiles = fs.readdirSync(adaptersDir).filter(f => f.endsWith('.md') && !f.startsWith('_'));
 
@@ -845,7 +844,7 @@ async function contributeLearnings(upstreamRepo = 'your-org/wogi-flow', options
 
   try {
     // Create contribution file
-    const contributionDir = path.join(PROJECT_ROOT, '.workflow', 'contributions');
+    const contributionDir = path.join(PATHS.workflow, 'contributions');
     if (!fs.existsSync(contributionDir)) {
       fs.mkdirSync(contributionDir, { recursive: true });
     }
@@ -935,7 +934,7 @@ async function createAutoPR(upstreamRepo, options = {}) {
 
   try {
     // Clone fork, create branch, add files, push, create PR
-    const tempDir = path.join(PROJECT_ROOT, '.workflow', 'temp-pr');
+    const tempDir = path.join(PATHS.workflow, 'temp-pr');
 
     console.log(`${colors.cyan}Creating PR automatically...${colors.reset}`);
 
@@ -1136,12 +1135,12 @@ if (require.main === module) {
       }
 
       // Save export file
-      const exportPath = path.join(PROJECT_ROOT, '.workflow', 'learnings-export.json');
+      const exportPath = path.join(PATHS.workflow, 'learnings-export.json');
       fs.writeFileSync(exportPath, JSON.stringify(data, null, 2));
       console.log(`\n${colors.green}✅ Exported to: ${exportPath}${colors.reset}`);
 
       // Also create PR-ready markdown
-      const prPath = path.join(PROJECT_ROOT, '.workflow', 'learnings-contribution.md');
+      const prPath = path.join(PATHS.workflow, 'learnings-contribution.md');
       fs.writeFileSync(prPath, formatExportForPR(data));
       console.log(`${colors.green}✅ PR-ready format: ${prPath}${colors.reset}`);
 

package/scripts/flow-aggregate.js

@@ -16,7 +16,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const readline = require('node:readline');
+const readline = require('node:readline/promises');
 const {
   PATHS,
   PROJECT_ROOT,
@@ -36,7 +36,7 @@ const { syncDecisionsToRules } = require('./flow-rules-sync');
 // ============================================================
 
 const SKILLS_DIR = PATHS.skills;
-const CORRECTIONS_DIR = path.join(PROJECT_ROOT, '.workflow', 'corrections');
+const CORRECTIONS_DIR = PATHS.corrections;
 
 // ============================================================
 // Data Collection
@@ -386,7 +386,7 @@ async function runPromotionWizard(data) {
     output: process.stdout
   });
 
-  const prompt = (q) => new Promise(r => rl.question(q, r));
+  const prompt = (q) => rl.question(q);
 
   console.log(color('cyan', 'Pattern Promotion Wizard'));
   console.log('');
@@ -435,10 +435,15 @@ function appendToDecisions(pattern) {
   const entry = `\n## ${date} - Promoted Pattern\n\n**Rule**: ${pattern}\n**Source**: Aggregated from learnings (3+ occurrences)\n\n`;
 
   content += entry;
-  writeFile(decisionsPath, content);
 
-  // Sync to .claude/rules/ for Claude Code integration
-  syncDecisionsToRules();
+  // Route through orchestrator for locking and dedup
+  try {
+    const { writeToDecisions } = require('./flow-learning-orchestrator');
+    writeToDecisions({ content, entryText: pattern, caller: 'flow-aggregate/appendToDecisions', syncRules: true }).catch(() => {});
+  } catch (_err) {
+    writeFile(decisionsPath, content);
+    syncDecisionsToRules();
+  }
 }
 
 /**

package/scripts/flow-api-index.js

@@ -15,7 +15,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { getProjectRoot, getConfig, color, success, warn, error, safeJsonParse } = require('./flow-utils');
+const { getProjectRoot, getConfig, color, success, warn, error, safeJsonParse, PATHS } = require('./flow-utils');
 const {
   findSimilarItems,
   generateAIDecisionPrompt,
@@ -24,10 +24,8 @@ const {
 } = require('./flow-semantic-match');
 const { BaseScanner, PROJECT_ROOT } = require('./flow-scanner-base');
 
-const WORKFLOW_DIR = path.join(PROJECT_ROOT, '.workflow');
-const STATE_DIR = path.join(WORKFLOW_DIR, 'state');
-const INDEX_PATH = path.join(STATE_DIR, 'api-index.json');
-const MAP_PATH = path.join(STATE_DIR, 'api-map.md');
+const INDEX_PATH = path.join(PATHS.state, 'api-index.json');
+const MAP_PATH = path.join(PATHS.state, 'api-map.md');
 
 // ============================================================
 // Configuration
@@ -568,7 +566,7 @@ class APIScanner extends BaseScanner {
    */
   save() {
     this.prune();
-    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.mkdirSync(PATHS.state, { recursive: true });
     fs.writeFileSync(INDEX_PATH, JSON.stringify(this.registry, null, 2));
     success(`Saved to ${path.relative(PROJECT_ROOT, INDEX_PATH)}`);
   }

package/scripts/flow-assumption-detector.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * Assumption Detector Library
  *

package/scripts/flow-audit.js

@@ -95,11 +95,24 @@ function findTodos() {
           if (!line) continue;
           const match = line.match(/^(.+):(\d+):(.+)$/);
           if (match) {
+            const file = match[1];
+            const text = match[3].trim();
+
+            // Exclude self-references: the TODO scanner's own code mentions
+            // TODO/FIXME/HACK as search patterns, not as actual action items.
+            // Also exclude lines that are clearly about scanning for TODOs
+            // (e.g., pattern arrays, grep invocations, variable names).
+            if (file === 'scripts/flow-audit.js') continue;
+
+            // Skip lines where the pattern appears only inside a string literal
+            // used as a search term (e.g., patterns = ['TODO', 'FIXME', ...])
+            if (/\[\s*['"](?:TODO|FIXME|HACK|WORKAROUND|TEMPORARY)['"]/.test(text)) continue;
+
             results.push({
               type: pattern,
-              file: match[1],
+              file,
               line: parseInt(match[2], 10),
-              text: match[3].trim()
+              text
             });
           }
         }

package/scripts/flow-auto-context.js

@@ -55,8 +55,6 @@ try {
   // Smart context gatherer not available - that's ok
 }
 
-const PROJECT_ROOT = getProjectRoot();
-
 // ============================================================
 // Index Freshness Check
 // ============================================================
@@ -241,7 +239,7 @@ function inferTaskType(keywords) {
  */
 function searchTraces(keywords) {
   const results = [];
-  const tracesDir = path.join(PATHS.traces || path.join(PATHS.workflow, 'traces'));
+  const tracesDir = path.join(PATHS.traces || PATHS.traces);
 
   if (!fs.existsSync(tracesDir)) return results;
 
@@ -278,7 +276,7 @@ function searchTraces(keywords) {
 
           results.push({
             source: 'trace',
-            path: path.relative(PROJECT_ROOT, tracePath),
+            path: path.relative(PATHS.root, tracePath),
             name: traceName,
             query: queryMatch ? queryMatch[1] : traceName,
             status: statusMatch ? statusMatch[1] : 'unknown',
@@ -415,7 +413,7 @@ function searchComponentIndex(keywords, config = null) {
  */
 function grepCodebase(keywords, maxResults = 10, config = null) {
   const results = [];
-  const srcDir = path.join(PROJECT_ROOT, 'src');
+  const srcDir = path.join(PATHS.root, 'src');
 
   if (!fs.existsSync(srcDir)) return results;
 
@@ -453,7 +451,7 @@ function grepCodebase(keywords, maxResults = 10, config = null) {
       for (const file of files) {
         if (results.length >= effectiveMaxResults) break;
 
-        const relPath = path.relative(PROJECT_ROOT, file);
+        const relPath = path.relative(PATHS.root, file);
         if (!results.some(r => r.path === relPath)) {
           // Optionally read file content with truncation
           let content = null;
@@ -637,11 +635,9 @@ async function enrichWithLSP(fileResults, config) {
   if (filesToEnrich.length === 0) return fileResults;
 
   try {
-    // Create timeout with cleanup to prevent resource leak
-    let timeoutId;
-    const timeoutPromise = new Promise(resolve => {
-      timeoutId = setTimeout(() => resolve(filesToEnrich), timeout);
-    });
+    // Create timeout with cleanup using AbortController
+    const ac = new AbortController();
+    const timeoutPromise = require('node:timers/promises').setTimeout(timeout, filesToEnrich, { signal: ac.signal }).catch(() => filesToEnrich);
 
     const enriched = await Promise.race([
       Promise.all(filesToEnrich.map(async (result) => {
@@ -670,7 +666,7 @@ async function enrichWithLSP(fileResults, config) {
     ]);
 
     // Clean up timeout to prevent resource leak
-    clearTimeout(timeoutId);
+    ac.abort();
 
     // Merge enriched results back into full list
     const enrichedMap = new Map(enriched.map(r => [r.path, r]));

package/scripts/flow-auto-learn.js

@@ -202,6 +202,7 @@ function loadAutoPatterns() {
 
 /**
  * Save auto-captured patterns back to feedback-patterns.md
+ * Routes through the learning orchestrator for locking and dedup.
  * @param {Array} patterns - Array of pattern objects
  */
 function saveAutoPatterns(patterns) {
@@ -211,31 +212,35 @@ function saveAutoPatterns(patterns) {
   }
 
   try {
-    let content = fs.readFileSync(FEEDBACK_PATTERNS_PATH, 'utf-8');
+    const { modifyFeedbackPatterns } = require('./flow-learning-orchestrator');
 
-    // Build new table (using DRY constants)
-    const rows = patterns.map(p =>
-      `| ${p.date} | ${p.pattern} | ${p.source} | ${p.count} | ${p.confidence}% | ${p.status} |`
-    );
+    modifyFeedbackPatterns((currentContent) => {
+      let content = currentContent;
 
-    const newSection = `${TABLE_FORMAT.sectionHeader}\n\n${TABLE_FORMAT.header}\n${TABLE_FORMAT.separator}\n${rows.join('\n')}`;
-
-    // Replace or add section
-    if (content.includes('## Auto-Captured Patterns')) {
-      content = content.replace(
-        /## Auto-Captured Patterns[\s\S]*?(?=\n## |\n---\n\n## |$)/,
-        newSection + '\n\n'
+      // Build new table (using DRY constants)
+      const rows = patterns.map(p =>
+        `| ${p.date} | ${p.pattern} | ${p.source} | ${p.count} | ${p.confidence}% | ${p.status} |`
       );
-    } else {
-      // Add before "## Promotion History" or at the end
-      if (content.includes('## Promotion History')) {
-        content = content.replace('## Promotion History', newSection + '\n\n---\n\n## Promotion History');
+
+      const newSection = `${TABLE_FORMAT.sectionHeader}\n\n${TABLE_FORMAT.header}\n${TABLE_FORMAT.separator}\n${rows.join('\n')}`;
+
+      // Replace or add section
+      if (content.includes('## Auto-Captured Patterns')) {
+        content = content.replace(
+          /## Auto-Captured Patterns[\s\S]*?(?=\n## |\n---\n\n## |$)/,
+          newSection + '\n\n'
+        );
       } else {
-        content = content.trimEnd() + '\n\n---\n\n' + newSection + '\n';
+        // Add before "## Promotion History" or at the end
+        if (content.includes('## Promotion History')) {
+          content = content.replace('## Promotion History', newSection + '\n\n---\n\n## Promotion History');
+        } else {
+          content = content.trimEnd() + '\n\n---\n\n' + newSection + '\n';
+        }
       }
-    }
 
-    fs.writeFileSync(FEEDBACK_PATTERNS_PATH, content, 'utf-8');
+      return { content, entryText: null }; // Bulk rewrite, no single entry dedup
+    }, { caller: 'flow-auto-learn/saveAutoPatterns', skipDedup: true });
   } catch (err) {
     warn(`Could not save feedback-patterns.md: ${err.message}`);
   }
@@ -449,6 +454,7 @@ function handlePromotion(pattern, config) {
 
 /**
  * Promote pattern to decisions.md
+ * Routes through the learning orchestrator for locking and dedup.
  * @param {Object} pattern - Pattern to promote
  */
 function promoteToDecisions(pattern) {
@@ -458,37 +464,39 @@ function promoteToDecisions(pattern) {
   }
 
   try {
-    let content = fs.readFileSync(DECISIONS_PATH, 'utf-8');
+    const { modifyDecisions } = require('./flow-learning-orchestrator');
+    const today = getTodayDate();
+    const escapedPattern = pattern.pattern.replace(/[#*_\[\]()\\]/g, '\\$&');
 
-    // Find Coding Standards section
-    const sectionHeader = '## Coding Standards';
+    modifyDecisions((currentContent) => {
+      let content = currentContent;
 
-    if (!content.includes(sectionHeader)) {
-      warn(`Could not promote pattern: Coding Standards section not found in decisions.md`);
-      return;
-    }
+      // Find Coding Standards section
+      const sectionHeader = '## Coding Standards';
 
-    // Generate rule entry (escape markdown special characters in pattern name)
-    const today = getTodayDate();
-    const escapedPattern = pattern.pattern.replace(/[#*_\[\]()\\]/g, '\\$&');
-    const ruleEntry = `\n### ${escapedPattern} (${today})
+      if (!content.includes(sectionHeader)) {
+        warn(`Could not promote pattern: Coding Standards section not found in decisions.md`);
+        return null;
+      }
+
+      // Generate rule entry
+      const ruleEntry = `\n### ${escapedPattern} (${today})
 **Source**: Auto-learned from ${pattern.count} occurrences (${pattern.source})
 **Rule**: [Describe the pattern rule here]
 `;
 
-    // Insert after Coding Standards header
-    const insertPoint = content.indexOf(sectionHeader) + sectionHeader.length;
-    const nextSection = content.indexOf('\n## ', insertPoint);
+      // Insert after Coding Standards header
+      const insertPoint = content.indexOf(sectionHeader) + sectionHeader.length;
+      const nextSection = content.indexOf('\n## ', insertPoint);
 
-    if (nextSection > insertPoint) {
-      // Insert before next section
-      content = content.slice(0, nextSection) + ruleEntry + content.slice(nextSection);
-    } else {
-      // Append to section
-      content = content.slice(0, insertPoint) + ruleEntry + content.slice(insertPoint);
-    }
+      if (nextSection > insertPoint) {
+        content = content.slice(0, nextSection) + ruleEntry + content.slice(nextSection);
+      } else {
+        content = content.slice(0, insertPoint) + ruleEntry + content.slice(insertPoint);
+      }
 
-    fs.writeFileSync(DECISIONS_PATH, content, 'utf-8');
+      return { content, entryText: pattern.pattern };
+    }, { caller: 'flow-auto-learn/promoteToDecisions', syncRules: true });
 
     // Update pattern status
     const patterns = loadAutoPatterns();
@@ -497,14 +505,6 @@ function promoteToDecisions(pattern) {
       updated.status = 'Promoted';
       saveAutoPatterns(patterns);
     }
-
-    // Sync rules
-    try {
-      require('./flow-rules-sync');
-    } catch (syncErr) {
-      // Log the failure for debugging
-      info(`Note: Rules sync skipped - ${syncErr.code === 'MODULE_NOT_FOUND' ? 'module not found' : syncErr.message}`);
-    }
   } catch (err) {
     warn(`Could not promote to decisions.md: ${err.message}`);
   }