agileflow 3.4.0 → 3.4.1

package/scripts/lib/audit-registry.js

@@ -132,6 +132,62 @@ const AUDIT_TYPES = {
     deep_analyzers: ['handlers', 'routes', 'api', 'stubs', 'state', 'imports', 'conditional'],
   },
 
+  brainstorm: {
+    name: 'Feature Brainstorm',
+    prefix: 'Brain',
+    color: '#c0caf5', // lavender
+    command: 'ideate/features',
+    analyzers: {
+      features: { subagent_type: 'brainstorm-analyzer-features', label: 'Feature Gaps' },
+      ux: { subagent_type: 'brainstorm-analyzer-ux', label: 'UX Improvements' },
+      market: { subagent_type: 'brainstorm-analyzer-market', label: 'Market Features' },
+      growth: { subagent_type: 'brainstorm-analyzer-growth', label: 'Growth & Engagement' },
+      integration: { subagent_type: 'brainstorm-analyzer-integration', label: 'Integrations' },
+    },
+    consensus: { subagent_type: 'brainstorm-consensus', label: 'Brainstorm Consensus' },
+    quick_analyzers: ['features', 'ux', 'market'],
+    deep_analyzers: ['features', 'ux', 'market', 'growth', 'integration'],
+  },
+
+  ideate: {
+    name: 'Ideation',
+    prefix: 'Idea',
+    color: '#ff9e64', // orange
+    command: 'ideate/new',
+    analyzers: {
+      security: { subagent_type: 'agileflow-security', label: 'Security' },
+      performance: { subagent_type: 'agileflow-performance', label: 'Performance' },
+      refactor: { subagent_type: 'agileflow-refactor', label: 'Code Quality' },
+      ui: { subagent_type: 'agileflow-ui', label: 'UX/Design' },
+      testing: { subagent_type: 'agileflow-testing', label: 'Testing' },
+      api: { subagent_type: 'agileflow-api', label: 'API/Architecture' },
+      accessibility: { subagent_type: 'agileflow-accessibility', label: 'Accessibility' },
+      compliance: { subagent_type: 'agileflow-compliance', label: 'Compliance' },
+      database: { subagent_type: 'agileflow-database', label: 'Database' },
+      monitoring: { subagent_type: 'agileflow-monitoring', label: 'Monitoring' },
+      qa: { subagent_type: 'agileflow-qa', label: 'QA' },
+      analytics: { subagent_type: 'agileflow-analytics', label: 'Analytics' },
+      documentation: { subagent_type: 'agileflow-documentation', label: 'Documentation' },
+    },
+    consensus: null, // ideation does its own synthesis (no consensus coordinator)
+    quick_analyzers: ['security', 'performance', 'refactor', 'ui', 'testing', 'api'],
+    deep_analyzers: [
+      'security',
+      'performance',
+      'refactor',
+      'ui',
+      'testing',
+      'api',
+      'accessibility',
+      'compliance',
+      'database',
+      'monitoring',
+      'qa',
+      'analytics',
+      'documentation',
+    ],
+  },
+
   legal: {
     name: 'Legal Risk',
     prefix: 'Legal',
@@ -167,7 +223,7 @@ const AUDIT_TYPES = {
 /**
  * Get audit type configuration.
  *
- * @param {string} type - Audit type key (logic, security, performance, test, completeness, legal)
+ * @param {string} type - Audit type key (logic, security, performance, test, completeness, legal, ideate)
  * @returns {object|null} Audit type config or null if invalid
  */
 function getAuditType(type) {
@@ -195,7 +251,7 @@ function getAnalyzersForAudit(type, depth, focus) {
   const audit = AUDIT_TYPES[type];
   if (!audit) return null;
 
-  const effectiveDepth = depth === 'ultradeep' ? 'deep' : depth || 'quick';
+  const effectiveDepth = depth === 'ultradeep' || depth === 'extreme' ? 'deep' : depth || 'quick';
   const analyzerKeys = effectiveDepth === 'deep' ? audit.deep_analyzers : audit.quick_analyzers;
 
   // Filter by focus if specified

package/scripts/lib/configure-features.js

@@ -393,6 +393,25 @@ function enableFeature(feature, options = {}, version) {
   if (feature === 'agentteams') {
     settings.env = settings.env || {};
     settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+
+    // Register PostToolUse hooks for native team observability
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+    const observerCmd = 'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/native-team-observer.js';
+    for (const matcher of ['TeamCreate', 'SendMessage', 'ListTeams']) {
+      const exists = settings.hooks.PostToolUse.some(
+        h =>
+          h.matcher === matcher &&
+          h.hooks?.some(hk => hk.command && hk.command.includes('native-team-observer'))
+      );
+      if (!exists) {
+        settings.hooks.PostToolUse.push({
+          matcher,
+          hooks: [{ type: 'command', command: observerCmd, timeout: 5000 }],
+        });
+      }
+    }
+
     writeJSON('.claude/settings.json', settings);
     updateMetadata(
       {
@@ -408,6 +427,7 @@ function enableFeature(feature, options = {}, version) {
     );
     success('Native Agent Teams enabled');
     info('Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json');
+    info('Registered PostToolUse hooks for native team observability');
     info('Claude Code will use native TeamCreate/SendMessage tools');
     info('Fallback: subagent mode (Task/TaskOutput) when native is unavailable');
     return true;
@@ -954,6 +974,20 @@ function disableFeature(feature, version) {
         delete settings.env;
       }
     }
+
+    // Remove PostToolUse hooks for native team observer
+    if (settings.hooks?.PostToolUse) {
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+        h => !h.hooks?.some(hk => hk.command && hk.command.includes('native-team-observer'))
+      );
+      if (settings.hooks.PostToolUse.length === 0) {
+        delete settings.hooks.PostToolUse;
+      }
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+      }
+    }
+
     writeJSON('.claude/settings.json', settings);
     updateMetadata(
       {
@@ -969,6 +1003,7 @@ function disableFeature(feature, version) {
     );
     success('Native Agent Teams disabled');
     info('Removed CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS from .claude/settings.json');
+    info('Removed PostToolUse hooks for native team observer');
     info('AgileFlow will use subagent mode (Task/TaskOutput) for multi-agent orchestration');
     return true;
   }

package/scripts/lib/model-profiles.js

@@ -60,9 +60,10 @@ function isValidModel(model) {
  *
  * @param {string} model - Model name
  * @param {number} [analyzerCount=5] - Number of analyzers
- * @returns {{ multiplier: number, model: string, perAnalyzerCost: string }}
+ * @param {number} [partitions=1] - Number of partitions (extreme mode)
+ * @returns {{ multiplier: number, model: string, perAnalyzerCost: string, totalEstimate: string, partitions?: number, totalSessions?: number }}
  */
-function estimateCost(model, analyzerCount) {
+function estimateCost(model, analyzerCount, partitions) {
   let MODEL_PRICING;
   try {
     MODEL_PRICING = require('./team-events').MODEL_PRICING;
@@ -75,19 +76,38 @@ function estimateCost(model, analyzerCount) {
   }
 
   const count = analyzerCount || 5;
+  const partCount = typeof partitions === 'number' && partitions > 1 ? partitions : 1;
   const resolved = resolveModel(model);
   const pricing = MODEL_PRICING[resolved] || MODEL_PRICING.haiku;
   const haikuPricing = MODEL_PRICING.haiku;
 
   const multiplier = pricing.output / haikuPricing.output;
-  const perAnalyzer = `$${((pricing.input * 50000) / 1_000_000 + (pricing.output * 10000) / 1_000_000).toFixed(3)}`;
+  const perAnalyzerCostNum =
+    (pricing.input * 50000) / 1_000_000 + (pricing.output * 10000) / 1_000_000;
+  const perAnalyzer = `$${perAnalyzerCostNum.toFixed(3)}`;
 
-  return {
+  // For extreme mode: each partition has a coordinator + all analyzers as sub-agents
+  // Estimated cost per partition coordinator session in USD (~10k input + 2k output at haiku rates)
+  const coordinatorCostUSD = 0.05;
+  const totalSessions = partCount * count;
+  const totalCost =
+    partCount > 1
+      ? partCount * coordinatorCostUSD + totalSessions * perAnalyzerCostNum
+      : count * perAnalyzerCostNum;
+
+  const result = {
     multiplier: Math.round(multiplier * 100) / 100,
     model: resolved,
     perAnalyzerCost: perAnalyzer,
-    totalEstimate: `~$${(count * ((pricing.input * 50000) / 1_000_000 + (pricing.output * 10000) / 1_000_000)).toFixed(2)}`,
+    totalEstimate: `~$${totalCost.toFixed(2)}`,
   };
+
+  if (partCount > 1) {
+    result.partitions = partCount;
+    result.totalSessions = totalSessions;
+  }
+
+  return result;
 }
 
 module.exports = {

package/scripts/lib/quality-gates.js

@@ -561,6 +561,164 @@ function createValidationReport(gateResults, options = {}) {
   return lines.join('\n');
 }
 
+// ============================================================================
+// CI Feedback Loop
+// ============================================================================
+
+/**
+ * Default CI feedback loop configuration
+ */
+const CI_FEEDBACK_DEFAULTS = {
+  enabled: true,
+  max_rounds: 3,
+};
+
+/**
+ * Load CI feedback loop config from agileflow-metadata.json
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} CI feedback loop config
+ */
+function loadCIFeedbackConfig(projectRoot) {
+  const metadataPath = path.join(projectRoot, 'docs', '00-meta', 'agileflow-metadata.json');
+  try {
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      if (metadata.ci_feedback_loops) {
+        return {
+          ...CI_FEEDBACK_DEFAULTS,
+          ...metadata.ci_feedback_loops,
+        };
+      }
+    }
+  } catch {
+    // Fall through to defaults
+  }
+  return { ...CI_FEEDBACK_DEFAULTS };
+}
+
+/**
+ * Execute a CI feedback loop - runs gates, and if they fail, returns
+ * structured feedback for the agent to retry (up to max_rounds).
+ *
+ * This implements the Stripe "Minions" pattern: deterministic CI check
+ * followed by agent retry, with a hard iteration limit.
+ *
+ * @param {Object[]} gates - Quality gate definitions to check
+ * @param {Object} options - Loop options
+ * @param {string} [options.projectRoot] - Project root directory
+ * @param {number} [options.maxRounds] - Override max retry rounds (default: from config)
+ * @param {number} [options.currentRound] - Current round number (1-based, default: 1)
+ * @param {string} [options.cwd] - Working directory for gate execution
+ * @returns {Object} Loop result with status and agent feedback
+ */
+function executeCIFeedbackLoop(gates, options = {}) {
+  const { projectRoot = process.cwd(), maxRounds, currentRound = 1, cwd } = options;
+
+  const config = loadCIFeedbackConfig(projectRoot);
+
+  if (!config.enabled) {
+    return {
+      status: 'disabled',
+      message: 'CI feedback loops are disabled in agileflow-metadata.json',
+      should_retry: false,
+      round: currentRound,
+      max_rounds: 0,
+    };
+  }
+
+  const effectiveMaxRounds = maxRounds || config.max_rounds || CI_FEEDBACK_DEFAULTS.max_rounds;
+
+  // Execute all gates
+  const gateResults = executeGates(gates, { cwd, stopOnFailure: false });
+
+  if (gateResults.passed) {
+    return {
+      status: 'passed',
+      message: `All ${gateResults.passed_count} gates passed on round ${currentRound}`,
+      should_retry: false,
+      round: currentRound,
+      max_rounds: effectiveMaxRounds,
+      gate_results: gateResults,
+    };
+  }
+
+  // Gates failed - determine if we should retry
+  const hasRoundsLeft = currentRound < effectiveMaxRounds;
+
+  if (!hasRoundsLeft) {
+    return {
+      status: 'exhausted',
+      message: `Gates failed after ${currentRound}/${effectiveMaxRounds} rounds. Escalating to human.`,
+      should_retry: false,
+      round: currentRound,
+      max_rounds: effectiveMaxRounds,
+      gate_results: gateResults,
+      failures: gateResults.results
+        .filter(r => r.status === GATE_STATUS.FAILED || r.status === GATE_STATUS.ERROR)
+        .map(r => ({
+          gate: r.gate,
+          message: r.message,
+          output: r.output,
+          error: r.error,
+        })),
+    };
+  }
+
+  // Build structured feedback for agent retry
+  const failures = gateResults.results.filter(
+    r => r.status === GATE_STATUS.FAILED || r.status === GATE_STATUS.ERROR
+  );
+
+  const feedbackLines = [
+    `## CI Feedback Loop - Round ${currentRound}/${effectiveMaxRounds}`,
+    '',
+    `**${failures.length} gate(s) failed.** ${effectiveMaxRounds - currentRound} retry round(s) remaining.`,
+    '',
+    '### Failures',
+    '',
+  ];
+
+  for (const failure of failures) {
+    feedbackLines.push(`#### ${failure.gate} (${failure.type})`);
+    feedbackLines.push(`- **Status**: ${failure.status}`);
+    feedbackLines.push(`- **Message**: ${failure.message}`);
+    if (failure.output) {
+      feedbackLines.push('- **Output**:');
+      feedbackLines.push('```');
+      feedbackLines.push(failure.output);
+      feedbackLines.push('```');
+    }
+    if (failure.error) {
+      feedbackLines.push('- **Error**:');
+      feedbackLines.push('```');
+      feedbackLines.push(failure.error);
+      feedbackLines.push('```');
+    }
+    feedbackLines.push('');
+  }
+
+  feedbackLines.push('### Action Required');
+  feedbackLines.push('');
+  feedbackLines.push('Fix the failing gates above, then re-run verification.');
+
+  return {
+    status: 'retry',
+    message: `Round ${currentRound}/${effectiveMaxRounds} failed. Agent should fix and retry.`,
+    should_retry: true,
+    round: currentRound,
+    max_rounds: effectiveMaxRounds,
+    next_round: currentRound + 1,
+    gate_results: gateResults,
+    agent_feedback: feedbackLines.join('\n'),
+    failures: failures.map(r => ({
+      gate: r.gate,
+      message: r.message,
+      output: r.output,
+      error: r.error,
+    })),
+  };
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
@@ -595,4 +753,9 @@ module.exports = {
 
   // Reporting
   createValidationReport,
+
+  // CI Feedback Loop
+  CI_FEEDBACK_DEFAULTS,
+  loadCIFeedbackConfig,
+  executeCIFeedbackLoop,
 };

package/scripts/lib/signal-detectors.js

@@ -233,6 +233,24 @@ const FEATURE_DETECTORS = {
     });
   },
 
+  'scale-adaptive': signals => {
+    const { scale } = signals;
+    if (!scale || !scale.tier) return null;
+    // Only trigger when scale info provides actionable guidance
+    const rec = scale.recommendations;
+    if (!rec) return null;
+    // Suggest scale-adaptive workflow when project is not medium (the default)
+    if (scale.tier === 'medium') return null;
+    const label = scale.tier.charAt(0).toUpperCase() + scale.tier.slice(1);
+    return recommend('scale-adaptive', {
+      priority: scale.tier === 'enterprise' || scale.tier === 'large' ? 'medium' : 'low',
+      trigger: `${label} project detected (${scale.metrics.files} files, ${scale.metrics.stories} stories) — ${rec.description}`,
+      action: 'suggest',
+      command: '/agileflow:workflow',
+      phase: 'pre-story',
+    });
+  },
+
   // =========================================================================
   // PLANNING PHASE
   // =========================================================================
@@ -517,6 +535,29 @@ const FEATURE_DETECTORS = {
     });
   },
 
+  'ac-verify': signals => {
+    const { story, tests } = signals;
+    if (!story || story.status !== 'in-progress') return null;
+    if (!tests || tests.passing !== true) return null; // Only after tests pass
+    if (!storyHasAC(story)) return null;
+    // Check if AC already verified (count by index to avoid extra keys)
+    const acStatus = story.ac_status || {};
+    const acList = story.acceptance_criteria || story.ac || [];
+    const verifiedCount = acList.filter(
+      (_, i) =>
+        acStatus[i] === 'verified' || acStatus[i] === 'auto-verified' || acStatus[i] === true
+    ).length;
+    if (verifiedCount === acList.length) return null;
+    const unverifiedCount = acList.length - verifiedCount;
+    return recommend('ac-verify', {
+      priority: 'high',
+      trigger: `Tests pass but ${unverifiedCount}/${acList.length} AC unverified`,
+      action: 'suggest',
+      command: '/agileflow:audit',
+      phase: 'post-impl',
+    });
+  },
+
   // =========================================================================
   // POST-IMPLEMENTATION PHASE
   // =========================================================================
@@ -704,6 +745,7 @@ const PHASE_MAP = {
     'workflow',
     'template',
     'configure',
+    'scale-adaptive',
   ],
   planning: [
     'impact',
@@ -728,6 +770,7 @@ const PHASE_MAP = {
     'serve',
   ],
   'post-impl': [
+    'ac-verify',
     'review',
     'logic-audit',
     'docs',

package/scripts/lib/status-writer.js

@@ -0,0 +1,255 @@
+/**
+ * status-writer.js - Canonical write module for status.json mutations
+ *
+ * ALL status.json story updates should go through this module to ensure:
+ * 1. Atomic read-modify-write via file-lock.js
+ * 2. State machine validation on status transitions
+ * 3. Automatic dependency resolution when stories complete
+ *
+ * Usage:
+ *   const { updateStory, readStory } = require('./status-writer');
+ *   updateStory(rootDir, 'US-0042', { status: 'completed' });
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Lazy-load file-lock for atomic writes
+let _fileLock;
+function getFileLock() {
+  if (_fileLock === undefined) {
+    try {
+      _fileLock = require('./file-lock');
+    } catch (e) {
+      _fileLock = null;
+    }
+  }
+  return _fileLock;
+}
+
+// Lazy-load story-state-machine for transition validation
+let _stateMachine;
+function getStateMachine() {
+  if (_stateMachine === undefined) {
+    try {
+      _stateMachine = require('./story-state-machine');
+    } catch (e) {
+      _stateMachine = null;
+    }
+  }
+  return _stateMachine;
+}
+
+// Lazy-load paths module
+let _paths;
+function getPaths() {
+  if (_paths === undefined) {
+    try {
+      _paths = require('../../lib/paths');
+    } catch (e) {
+      _paths = null;
+    }
+  }
+  return _paths;
+}
+
+/**
+ * Resolve the status.json file path for a given project root.
+ * @param {string} rootDir - Project root directory
+ * @returns {string} Absolute path to status.json
+ */
+function getStatusFilePath(rootDir) {
+  const paths = getPaths();
+  if (paths && typeof paths.getStatusPath === 'function') {
+    return paths.getStatusPath(rootDir);
+  }
+  return path.join(rootDir, 'docs', '09-agents', 'status.json');
+}
+
+/**
+ * Read a single story from status.json.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {string} storyId - Story ID (e.g., 'US-0042')
+ * @returns {{ ok: boolean, story?: object, error?: string }}
+ */
+function readStory(rootDir, storyId) {
+  try {
+    const statusPath = getStatusFilePath(rootDir);
+    if (!fs.existsSync(statusPath)) {
+      return { ok: false, error: 'status.json not found' };
+    }
+
+    const data = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    if (!data.stories || !data.stories[storyId]) {
+      return { ok: false, error: `Story ${storyId} not found` };
+    }
+
+    return { ok: true, story: data.stories[storyId] };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Resolve dependencies when a story transitions to completed/done.
+ * Pure in-memory operation — mutates `data` in place.
+ *
+ * Iterates all stories, finds those with `depends_on` or `blocked_by`
+ * containing `completedStoryId`. If all dependencies are now
+ * completed/done, transitions the story from `blocked` → `ready`.
+ *
+ * @param {object} data - Full status.json data object (mutated in place)
+ * @param {string} completedStoryId - The story that just completed
+ * @returns {{ unblocked: string[] }} List of story IDs that were unblocked
+ */
+function resolveDependencies(data, completedStoryId) {
+  const unblocked = [];
+  if (!data || !data.stories) return { unblocked };
+
+  const sm = getStateMachine();
+  const completedStatuses = sm ? sm.COMPLETED_STATUSES : ['completed', 'archived'];
+
+  // Helper: check if a story ID is in a completed/done state
+  function isCompleted(sid) {
+    const s = data.stories[sid];
+    if (!s) return false;
+    return completedStatuses.includes(s.status) || s.status === 'done';
+  }
+
+  for (const [storyId, story] of Object.entries(data.stories)) {
+    // Only consider blocked stories
+    if (story.status !== 'blocked') continue;
+
+    // Collect dependency IDs from both fields
+    const deps = [];
+    if (Array.isArray(story.depends_on)) deps.push(...story.depends_on);
+    if (Array.isArray(story.blocked_by)) deps.push(...story.blocked_by);
+
+    // Skip stories that don't depend on the completed story
+    if (!deps.includes(completedStoryId)) continue;
+
+    // Check if ALL dependencies are now completed/done
+    const allMet = deps.every(depId => isCompleted(depId));
+    if (!allMet) continue;
+
+    // Transition blocked → ready
+    if (sm) {
+      const result = sm.transition({ id: storyId, status: 'blocked' }, 'ready', {
+        actor: 'status-writer',
+        reason: `Dependencies resolved (${completedStoryId} completed)`,
+      });
+      if (result.success) {
+        story.status = 'ready';
+        story.updated_at = new Date().toISOString();
+        unblocked.push(storyId);
+      }
+    } else {
+      // No state machine available — direct transition
+      story.status = 'ready';
+      story.updated_at = new Date().toISOString();
+      unblocked.push(storyId);
+    }
+  }
+
+  return { unblocked };
+}
+
+/**
+ * Update a single story in status.json using atomic read-modify-write.
+ *
+ * When `updates.status` is provided and differs from the current status,
+ * validates the transition via story-state-machine. When transitioning
+ * to completed/done, triggers resolveDependencies() automatically.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {string} storyId - Story ID (e.g., 'US-0042')
+ * @param {object} updates - Fields to update (e.g., { status: 'completed', assigned_to: 'AG-API' })
+ * @param {object} [options={}] - Options
+ * @param {boolean} [options.skipValidation=false] - Skip state machine validation
+ * @returns {{ ok: boolean, unblocked?: string[], error?: string }}
+ */
+function updateStory(rootDir, storyId, updates, options = {}) {
+  const { skipValidation = false } = options;
+
+  try {
+    const statusPath = getStatusFilePath(rootDir);
+    if (!fs.existsSync(statusPath)) {
+      return { ok: false, error: 'status.json not found' };
+    }
+
+    const fileLock = getFileLock();
+
+    // Mutation function applied inside the lock
+    let resultMeta = { unblocked: [] };
+
+    const modifyFn = data => {
+      if (!data.stories) data.stories = {};
+      if (!data.stories[storyId]) {
+        throw new Error(`Story ${storyId} not found`);
+      }
+
+      const story = data.stories[storyId];
+
+      // Validate status transition if status is changing
+      if (updates.status && updates.status !== story.status && !skipValidation) {
+        const sm = getStateMachine();
+        if (sm) {
+          const valid = sm.isValidTransition(story.status, updates.status);
+          if (!valid) {
+            const validTargets = sm.getValidTransitions(story.status);
+            throw new Error(
+              `Invalid transition: ${story.status} → ${updates.status}. ` +
+                `Valid transitions: ${validTargets.join(', ') || 'none'}`
+            );
+          }
+        }
+      }
+
+      // Apply updates (null values delete the field)
+      Object.assign(story, updates);
+      for (const [key, val] of Object.entries(updates)) {
+        if (val === null) delete story[key];
+      }
+      story.updated_at = new Date().toISOString();
+
+      // Trigger dependency resolution on completion
+      const sm = getStateMachine();
+      const completedStatuses = sm ? sm.COMPLETED_STATUSES : ['completed', 'archived'];
+      if (
+        updates.status &&
+        (completedStatuses.includes(updates.status) || updates.status === 'done')
+      ) {
+        const resolved = resolveDependencies(data, storyId);
+        resultMeta.unblocked = resolved.unblocked;
+      }
+
+      return data;
+    };
+
+    if (fileLock && typeof fileLock.atomicReadModifyWrite === 'function') {
+      const result = fileLock.atomicReadModifyWrite(statusPath, modifyFn);
+      if (!result.success) {
+        return { ok: false, error: result.error || 'Atomic write failed' };
+      }
+    } else {
+      // Fallback: direct read-modify-write (no lock)
+      const data = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+      const modified = modifyFn(data);
+      fs.writeFileSync(statusPath, JSON.stringify(modified, null, 2) + '\n');
+    }
+
+    return { ok: true, unblocked: resultMeta.unblocked };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+module.exports = {
+  updateStory,
+  readStory,
+  resolveDependencies,
+  getStatusFilePath,
+};