@comfanion/workflow 4.38.1-dev.8 → 4.38.1

package/src/opencode/plugins/file-indexer.ts

@@ -26,8 +26,12 @@ let logFilePath: string | null = null
 // Log to file only
 function logFile(msg: string): void {
   if (logFilePath) {
-    const timestamp = new Date().toISOString().slice(11, 19)
-    fsSync.appendFileSync(logFilePath, `${timestamp} ${msg}\n`)
+    try {
+      const timestamp = new Date().toISOString().slice(11, 19)
+      fsSync.appendFileSync(logFilePath, `${timestamp} ${msg}\n`)
+    } catch {
+      // Ignore write errors (e.g., ENOENT if log directory was removed)
+    }
   }
 }
 
@@ -183,6 +187,7 @@ async function loadConfig(projectRoot: string): Promise<VectorizerConfig> {
       exclude = excludeMatch[1].match(/-\s+(.+)/g)?.map(m => m.replace(/^-\s+/, '').trim()) || DEFAULT_CONFIG.exclude
     }
     
+    // TODO(BACKLOG): parse vectorizer.indexes from config.yaml to support custom extensions
     return { enabled, auto_index, debounce_ms, indexes: DEFAULT_CONFIG.indexes, exclude }
   } catch (e) {
     debug(`Failed to load config: ${(e as Error).message}`)
@@ -201,7 +206,11 @@ function getIndexForFile(filePath: string, config: VectorizerConfig): string | n
 }
 
 function isExcluded(relativePath: string, config: VectorizerConfig): boolean {
-  return config.exclude.some(pattern => relativePath.startsWith(pattern))
+  const norm = relativePath.replace(/\\/g, '/')
+  return config.exclude.some(pattern => {
+    const p = pattern.replace(/\\/g, '/').replace(/\/+$/, '')
+    return norm === p || norm.startsWith(`${p}/`) || norm.includes(`/${p}/`)
+  })
 }
 
 async function isVectorizerInstalled(projectRoot: string): Promise<boolean> {
@@ -258,20 +267,23 @@ async function ensureIndexOnSessionStart(
     for (const [indexName, indexConfig] of Object.entries(config.indexes)) {
       if (!indexConfig.enabled) continue
       const indexer = await new CodebaseIndexer(projectRoot, indexName).init()
-      const indexExists = await hasIndex(projectRoot, indexName)
-      
-      if (!indexExists) {
-        const health = await indexer.checkHealth(config.exclude)
-        totalExpectedFiles += health.expectedCount
-        needsWork = true
-      } else {
-        const health = await indexer.checkHealth(config.exclude)
-        if (health.needsReindex) {
+      try {
+        const indexExists = await hasIndex(projectRoot, indexName)
+        
+        if (!indexExists) {
+          const health = await indexer.checkHealth(config.exclude)
           totalExpectedFiles += health.expectedCount
           needsWork = true
+        } else {
+          const health = await indexer.checkHealth(config.exclude)
+          if (health.needsReindex) {
+            totalExpectedFiles += health.expectedCount
+            needsWork = true
+          }
         }
+      } finally {
+        await indexer.unloadModel()
       }
-      await indexer.unloadModel()
     }
     
     // Notify about work to do
@@ -287,47 +299,48 @@ async function ensureIndexOnSessionStart(
       const startTime = Date.now()
       
       const indexer = await new CodebaseIndexer(projectRoot, indexName).init()
-      
-      if (!indexExists) {
-        log(`Creating "${indexName}" index...`)
-        const stats = await indexer.indexAll((indexed: number, total: number, file: string) => {
-          if (indexed % 10 === 0 || indexed === total) {
-            logFile(`"${indexName}": ${indexed}/${total} - ${file}`)
-          }
-        }, config.exclude)
-        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
-        log(`"${indexName}": done ${stats.indexed} files (${elapsed}s)`)
-        totalFiles += stats.indexed
-        action = 'created'
-      } else {
-        const health = await indexer.checkHealth(config.exclude)
-        
-        if (health.needsReindex) {
-          log(`Rebuilding "${indexName}" (${health.reason}: ${health.currentCount} vs ${health.expectedCount} files)...`)
+      try {
+        if (!indexExists) {
+          log(`Creating "${indexName}" index...`)
           const stats = await indexer.indexAll((indexed: number, total: number, file: string) => {
             if (indexed % 10 === 0 || indexed === total) {
               logFile(`"${indexName}": ${indexed}/${total} - ${file}`)
             }
           }, config.exclude)
           const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
-          log(`"${indexName}": rebuilt ${stats.indexed} files (${elapsed}s)`)
+          log(`"${indexName}": done ${stats.indexed} files (${elapsed}s)`)
           totalFiles += stats.indexed
-          action = 'rebuilt'
+          action = 'created'
         } else {
-          log(`Freshening "${indexName}"...`)
-          const stats = await indexer.freshen()
-          const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
+          const health = await indexer.checkHealth(config.exclude)
           
-          if (stats.updated > 0 || stats.deleted > 0) {
-            log(`"${indexName}": +${stats.updated} -${stats.deleted} (${elapsed}s)`)
-            action = 'freshened'
+          if (health.needsReindex) {
+            log(`Rebuilding "${indexName}" (${health.reason}: ${health.currentCount} vs ${health.expectedCount} files)...`)
+            const stats = await indexer.indexAll((indexed: number, total: number, file: string) => {
+              if (indexed % 10 === 0 || indexed === total) {
+                logFile(`"${indexName}": ${indexed}/${total} - ${file}`)
+              }
+            }, config.exclude)
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
+            log(`"${indexName}": rebuilt ${stats.indexed} files (${elapsed}s)`)
+            totalFiles += stats.indexed
+            action = 'rebuilt'
           } else {
-            log(`"${indexName}": fresh (${elapsed}s)`)
+            log(`Freshening "${indexName}"...`)
+            const stats = await indexer.freshen()
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
+            
+            if (stats.updated > 0 || stats.deleted > 0) {
+              log(`"${indexName}": +${stats.updated} -${stats.deleted} (${elapsed}s)`)
+              action = 'freshened'
+            } else {
+              log(`"${indexName}": fresh (${elapsed}s)`)
+            }
           }
         }
+      } finally {
+        await indexer.unloadModel()
       }
-      
-      await indexer.unloadModel()
     }
     
     elapsedSeconds = (Date.now() - overallStart) / 1000
@@ -364,21 +377,22 @@ async function processPendingFiles(projectRoot: string, config: VectorizerConfig
     
     for (const [indexName, files] of filesToProcess.entries()) {
       const indexer = await new CodebaseIndexer(projectRoot, indexName).init()
-      
-      for (const filePath of files) {
-        try {
-          const wasIndexed = await indexer.indexSingleFile(filePath)
-          if (wasIndexed) {
-            log(`Reindexed: ${path.relative(projectRoot, filePath)} → ${indexName}`)
-          } else {
-            logFile(`Skipped (unchanged): ${path.relative(projectRoot, filePath)}`)
+      try {
+        for (const filePath of files) {
+          try {
+            const wasIndexed = await indexer.indexSingleFile(filePath)
+            if (wasIndexed) {
+              log(`Reindexed: ${path.relative(projectRoot, filePath)} → ${indexName}`)
+            } else {
+              logFile(`Skipped (unchanged): ${path.relative(projectRoot, filePath)}`)
+            }
+          } catch (e) {
+            log(`Error reindexing ${path.relative(projectRoot, filePath)}: ${(e as Error).message}`)
           }
-        } catch (e) {
-          log(`Error reindexing ${path.relative(projectRoot, filePath)}: ${(e as Error).message}`)
         }
+      } finally {
+        await indexer.unloadModel()
       }
-      
-      await indexer.unloadModel()
     }
   } catch (e) {
     debug(`Fatal: ${(e as Error).message}`)
@@ -409,7 +423,12 @@ export const FileIndexerPlugin: Plugin = async ({ directory, client }) => {
   
   // Setup log file
   logFilePath = path.join(directory, '.opencode', 'indexer.log')
-  fsSync.writeFileSync(logFilePath, '') // Clear old log
+  try {
+    fsSync.writeFileSync(logFilePath, '') // Clear old log
+  } catch {
+    if (DEBUG) console.log(`[file-indexer] log init failed`)
+    logFilePath = null // Disable file logging if can't write
+  }
   
   log(`Plugin ACTIVE`)
   
@@ -449,6 +468,11 @@ export const FileIndexerPlugin: Plugin = async ({ directory, client }) => {
   function queueFileForIndexing(filePath: string): void {
     const relativePath = path.relative(directory, filePath)
     
+    // Reject paths outside project directory
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      return
+    }
+    
     // Check exclusions from config
     if (isExcluded(relativePath, config)) {
       return
@@ -468,6 +492,7 @@ export const FileIndexerPlugin: Plugin = async ({ directory, client }) => {
         await processPendingFiles(directory, config)
       } else {
         debug(`Vectorizer not installed`)
+        pendingFiles.clear() // Prevent unbounded growth when vectorizer is not installed
       }
     }, config.debounce_ms + 100)
   }

package/src/opencode/plugins/version-check.ts

@@ -49,23 +49,34 @@ async function getLocalVersion(directory: string): Promise<string | null> {
 
 async function getLatestVersion(): Promise<string | null> {
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => resolve(null), 5000) // 5s timeout
-    
-    https.get(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, (res) => {
+    let settled = false
+    const done = (value: string | null) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      resolve(value)
+    }
+
+    const timeout = setTimeout(() => {
+      done(null)
+      req.destroy() // Destroy socket on timeout to prevent leak
+    }, 5000)
+
+    const req = https.get(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, (res) => {
       let data = ''
-      res.on('data', chunk => data += chunk)
+      res.on('data', chunk => {
+        if (!settled) data += chunk // Stop accumulating after settled
+      })
       res.on('end', () => {
-        clearTimeout(timeout)
         try {
           const json = JSON.parse(data)
-          resolve(json.version || null)
+          done(json.version || null)
         } catch {
-          resolve(null)
+          done(null)
         }
       })
     }).on('error', () => {
-      clearTimeout(timeout)
-      resolve(null)
+      done(null)
     })
   })
 }
@@ -88,8 +99,10 @@ async function saveCache(directory: string, cache: VersionCache): Promise<void>
 }
 
 function compareVersions(local: string, latest: string): number {
-  const localParts = local.split('.').map(Number)
-  const latestParts = latest.split('.').map(Number)
+  // Strip pre-release suffix (e.g., "4.38.1-beta.1" → "4.38.1")
+  const strip = (v: string) => v.replace(/-.*$/, '')
+  const localParts = strip(local).split('.').map(Number)
+  const latestParts = strip(latest).split('.').map(Number)
   
   for (let i = 0; i < 3; i++) {
     const l = localParts[i] || 0
@@ -111,14 +124,34 @@ async function getLanguage(directory: string): Promise<'en' | 'uk' | 'ru'> {
   try {
     const configPath = path.join(directory, '.opencode', 'config.yaml')
     const config = await fs.readFile(configPath, 'utf8')
-    if (config.includes('communication_language: Ukrainian') || config.includes('communication_language: uk')) return 'uk'
-    if (config.includes('communication_language: Russian') || config.includes('communication_language: ru')) return 'ru'
+    const match = config.match(/communication_language:\s*["']?(\w+)["']?/i)
+    const lang = match?.[1]?.toLowerCase()
+    if (lang === 'ukrainian' || lang === 'uk') return 'uk'
+    if (lang === 'russian' || lang === 'ru') return 'ru'
   } catch {}
   return 'en'
 }
 
+async function loadVersionCheckConfig(directory: string): Promise<{ enabled: boolean; checkInterval: number }> {
+  try {
+    const configPath = path.join(directory, '.opencode', 'config.yaml')
+    const content = await fs.readFile(configPath, 'utf8')
+    const section = content.match(/version_check:\s*\n([\s\S]*?)(?=\n[a-z_]+:|$)/i)
+    if (!section) return { enabled: true, checkInterval: 60 * 60 * 1000 }
+    const enabledMatch = section[1].match(/^\s+enabled:\s*(true|false)/m)
+    const intervalMatch = section[1].match(/^\s+check_interval:\s*(\d+)/m)
+    return {
+      enabled: enabledMatch ? enabledMatch[1] === 'true' : true,
+      checkInterval: intervalMatch ? parseInt(intervalMatch[1]) : 60 * 60 * 1000,
+    }
+  } catch {
+    return { enabled: true, checkInterval: 60 * 60 * 1000 }
+  }
+}
+
 export const VersionCheckPlugin: Plugin = async ({ directory, client }) => {
-  const CHECK_INTERVAL = 60 * 60 * 1000 // 1 hour (you release often! 🚀)
+  const vcConfig = await loadVersionCheckConfig(directory)
+  const CHECK_INTERVAL = vcConfig.checkInterval
   
   const toast = async (message: string, variant: 'info' | 'success' | 'error' = 'info') => {
     try {
@@ -128,6 +161,14 @@ export const VersionCheckPlugin: Plugin = async ({ directory, client }) => {
   
   log(`Plugin loaded`)
   
+  // Respect config enabled flag
+  if (!vcConfig.enabled) {
+    log(`Plugin DISABLED by config`)
+    return {
+      event: async () => {},
+    }
+  }
+  
   // Run check after short delay (let TUI initialize)
   setTimeout(async () => {
     try {

package/src/opencode/skills/code-review/SKILL.md

@@ -16,6 +16,75 @@ How to perform thorough code reviews for implemented stories.
 
 Ensure code quality, correctness, and adherence to project standards before merging.
 
+---
+
+<workflow name="code-review">
+
+  <phase name="1-prepare" title="Preparation">
+    <action>Read the story file completely</action>
+    <action>Identify all acceptance criteria</action>
+    <action>Load docs/coding-standards/*.md for coding standards</action>
+    <action>Use search() to find similar patterns in codebase to compare against</action>
+    <action>Use search() in docs for architecture requirements</action>
+    <action>Review File List section for changed files</action>
+  </phase>
+
+  <phase name="2-security" title="Security Analysis (HIGH Priority)">
+    <critical>Security issues are ALWAYS high priority</critical>
+    <check>No hardcoded secrets, API keys, passwords</check>
+    <check>All user inputs validated and sanitized</check>
+    <check>Parameterized queries (no SQL injection)</check>
+    <check>Auth required on protected endpoints</check>
+    <check>Authorization checks before data access</check>
+    <check>Sensitive data not logged</check>
+    <check>Error messages don't leak internal details</check>
+  </phase>
+
+  <phase name="3-correctness" title="Correctness Analysis (HIGH Priority)">
+    <check>All acceptance criteria satisfied</check>
+    <check>Edge cases handled</check>
+    <check>Error scenarios have proper handling</check>
+    <check>No obvious logic errors</check>
+    <check>No race conditions</check>
+  </phase>
+
+  <phase name="4-tests" title="Testing Review (HIGH Priority)">
+    <check>Unit tests exist for new code</check>
+    <check>Tests cover happy path and errors</check>
+    <check>No flaky tests</check>
+    <check>Test names are descriptive</check>
+    <check>Run test suite: go test / npm test / pytest / cargo test</check>
+    <check>If failures → include in review report as HIGH priority</check>
+  </phase>
+
+  <phase name="5-quality" title="Code Quality (MEDIUM Priority)">
+    <check>Follows project architecture</check>
+    <check>Clear naming conventions</check>
+    <check>No code duplication</check>
+    <check>Functions are focused and small</check>
+    <check>Proper error wrapping</check>
+    <check>No N+1 query issues</check>
+    <check>Run linter: golangci-lint / eslint / ruff / cargo clippy</check>
+  </phase>
+
+  <phase name="6-write-file" title="Write Findings to Story File">
+    <critical>MANDATORY: Append review to story file for history/analytics</critical>
+    <step n="1">Read story file's ## Review section</step>
+    <step n="2">Count existing ### Review #N blocks → your review is N+1</step>
+    <step n="3">Append ### Review #N block with format below</step>
+    <step n="4">NEVER overwrite previous reviews — always APPEND</step>
+  </phase>
+
+  <phase name="7-return-summary" title="Return Summary to Caller">
+    <critical>Caller (@dev) uses YOUR output, not the file. Keep it actionable.</critical>
+    <step n="1">Return SHORT summary: verdict + action items</step>
+    <step n="2">Caller will use this directly without re-reading story file</step>
+  </phase>
+
+</workflow>
+
+---
+
 ## Review Process
 
 ### 1. Preparation
@@ -101,38 +170,82 @@ For each AC in the story:
 
 All criteria met. Code is ready to merge.
 
-```markdown
-### Review Outcome: Approve
-
-All acceptance criteria satisfied. Code follows project standards.
-Ready for merge.
-```
-
 ### 🔄 Changes Requested
 
 Issues found that need addressing.
 
+### ❌ Blocked
+
+Major issues that prevent approval.
+
+## Write Findings to Story File (MANDATORY)
+
+After completing the review, **append** your findings to the story file's `## Review` section.
+Each review round is a separate `### Review #N` block. NEVER overwrite previous reviews — always append.
+
+**How to determine review number:**
+1. Read the story file's `## Review` section
+2. Count existing `### Review #N` blocks
+3. Your review is `N + 1` (or `#1` if none exist)
+
+**Format to append at the end of the story file:**
+
 ```markdown
-### Review Outcome: Changes Requested
+### Review #{{N}} — {{YYYY-MM-DD}}
 
-**Action Items:**
-- [ ] [High] Fix missing error handling in X
-- [ ] [Med] Add unit test for edge case Y
-- [ ] [Low] Improve variable naming in Z
+**Verdict:** {{APPROVE | CHANGES_REQUESTED | BLOCKED}}
+**Reviewer:** @reviewer (Marcus)
+
+**Summary:** {{1-2 sentences}}
+
+**Tests:** {{PASS | FAIL — details}}
+**Lint:** {{PASS | FAIL — details}}
+
+{{IF issues found:}}
+#### Action Items
+- [ ] [HIGH] `path/file.ts:42` — {{issue}} → Fix: {{specific fix}}
+- [ ] [MED] `path/file.ts:100` — {{issue}} → Fix: {{specific fix}}
+- [ ] [LOW] `path/file.ts:15` — {{issue}}
+
+{{IF approve:}}
+#### What's Good
+- {{positive feedback}}
 ```
 
-### ❌ Blocked
+**Example — first review with issues:**
 
-Major issues that prevent approval.
+```markdown
+### Review #1 — 2026-01-27
+
+**Verdict:** CHANGES_REQUESTED
+**Reviewer:** @reviewer (Marcus)
+
+**Summary:** Missing error handling in CreateUser handler, no test for duplicate email.
+
+**Tests:** PASS (12/12)
+**Lint:** PASS
+
+#### Action Items
+- [ ] [HIGH] `internal/user/handler.go:42` — No error handling for DB timeout → Fix: wrap with domain error
+- [ ] [MED] `internal/user/handler_test.go` — Missing duplicate email test → Fix: add TestCreateUser_DuplicateEmail
+```
+
+**Example — second review after fixes:**
 
 ```markdown
-### Review Outcome: Blocked
+### Review #2 — 2026-01-27
+
+**Verdict:** APPROVE
+**Reviewer:** @reviewer (Marcus)
 
-**Blocking Issues:**
-1. Security vulnerability in authentication flow
-2. Missing critical test coverage
+**Summary:** All issues from Review #1 fixed. Error handling added, test coverage complete.
 
-Cannot proceed until blocking issues resolved.
+**Tests:** PASS (14/14)
+**Lint:** PASS
+
+#### What's Good
+- Clean error wrapping with domain errors
+- Good test coverage for edge cases
 ```
 
 ## Severity Levels
@@ -164,39 +277,53 @@ func foo() error { ... }
 
 ## Updating Story File
 
-After review, add to story file:
+**MANDATORY:** Use the format from "Write Findings to Story File" section above.
+Append `### Review #N` block to the `## Review` section at the end of the story file.
+NEVER overwrite previous reviews — history must be preserved for analytics.
 
-```markdown
-## Senior Developer Review (AI)
+## Return Summary to Caller (MANDATORY)
 
-### Review Date
-2024-01-15
+After writing to story file, return a SHORT summary to the calling agent (@dev).
+This prevents the caller from re-reading the story file.
 
-### Review Outcome
-Changes Requested
+**Format:**
 
-### Action Items
-- [ ] [High] Add error handling to CreateUser handler
-- [ ] [Med] Add unit test for duplicate email validation
-- [ ] [Low] Rename 'x' to 'userCount'
+```
+**VERDICT: {{APPROVE | CHANGES_REQUESTED | BLOCKED}}**
+
+{{IF CHANGES_REQUESTED or BLOCKED:}}
+Action items:
+- [HIGH] `path/file.ts:42` — {{issue}} → {{fix}}
+- [MED] `path/file.ts:100` — {{issue}} → {{fix}}
 
-### Detailed Comments
-[Include detailed review comments here]
+{{IF APPROVE:}}
+All good. No issues found.
 ```
 
-If changes requested, also add:
+**Example — Changes Requested:**
 
-```markdown
-### Review Follow-ups (AI)
+```
+**VERDICT: CHANGES_REQUESTED**
 
-- [ ] [AI-Review] [High] Add error handling to CreateUser handler
-- [ ] [AI-Review] [Med] Add unit test for duplicate email validation
+Action items:
+- [HIGH] `internal/user/handler.go:42` — No error handling for DB timeout → wrap with domain error
+- [MED] `internal/user/handler_test.go` — Missing duplicate email test → add TestCreateUser_DuplicateEmail
 ```
 
+**Example — Approve:**
+
+```
+**VERDICT: APPROVE**
+
+All good. No issues found. Clean error wrapping, good test coverage.
+```
+
+---
+
 ## Best Practices
 
 1. **Be specific** - Point to exact file and line
 2. **Suggest solutions** - Don't just criticize
 3. **Prioritize** - Focus on important issues first
 4. **Be constructive** - Phrase feedback positively
-5. **Use different LLM** - For fresh perspective
+5. **Use search()** - Find similar patterns before reviewing

package/src/opencode/skills/dev-epic/SKILL.md

@@ -78,27 +78,34 @@ metadata:
   </phase>
 
   <phase name="3-loop" title="Story Execution Loop">
+    <critical>Status flow: in_progress → review → done. NEVER mark done before review!</critical>
     <for-each item="story" in="pending_stories">
       
       <action name="execute-story">
         Follow /dev-story logic:
-        - Create nested TODO for tasks
-        - Implement all tasks (RED/GREEN/REFACTOR)
-        - Clear task TODO when done
+        - Read ONE story file
+        - Execute tasks ONE BY ONE (or parallel if independent)
+        - NEVER delegate entire story to @coder in one prompt
+        - After each task: verify, mark done, next task
       </action>
       
-      <action name="mark-done">
-        Mark story as completed in epic TODO
+      <action name="story-to-review">
+        All tasks done → set story status: review
+        Mark story TODO as "review" (NOT "done" yet!)
       </action>
       
-      <action name="review">
-        Mark "Review Story" as in_progress
-        Invoke @reviewer
+      <action name="review-story">
+        Invoke @reviewer on story code.
+        Reviewer does TWO things:
+        1. WRITES findings to story file (## Review → ### Review #N) — for history
+        2. RETURNS summary to you — use THIS, do NOT re-read story file
         <if condition="CHANGES_REQUESTED">
-          Add fix tasks → re-execute → re-review (max 3 attempts)
+          Use reviewer's returned action items directly.
+          Create fix tasks from action items → execute → re-review (max 3 attempts).
         </if>
         <if condition="APPROVED">
-          Mark "Review Story" as completed
+          Set story status: done
+          Mark story TODO as completed
         </if>
       </action>
       
@@ -111,20 +118,22 @@ metadata:
       
       <action name="compact">
         Mark next story as in_progress in TODO
-        Wait for auto-compaction
-        Plugin reads TODO + state → resume
+        Wait for auto-compaction → resume
       </action>
       
     </for-each>
   </phase>
 
   <phase name="4-finalize" title="Finalize Epic">
-    <step n="1">Run epic integration tests (mark in TODO)</step>
-    <step n="2">Verify all AC from epic file (mark in TODO)</step>
-    <step n="3">Set state: status="done"</step>
-    <step n="4">Clear epic TODO list</step>
-    <step n="5">Update .opencode/session-state.yaml (next epic or done)</step>
-    <step n="6">Report completion with summary</step>
+    <critical>Epic also goes through review before done!</critical>
+    <step n="1">All stories done → set epic status: review</step>
+    <step n="2">Run epic integration tests (mark in TODO)</step>
+    <step n="3">Verify all AC from epic file (mark in TODO)</step>
+    <step n="4">If tests fail → fix → re-test</step>
+    <step n="5">All passed → set epic status: done</step>
+    <step n="6">Clear epic TODO list</step>
+    <step n="7">Update .opencode/session-state.yaml (next epic or done)</step>
+    <step n="8">Report completion with summary</step>
   </phase>
 
 </workflow>
@@ -170,6 +179,11 @@ This file survives compaction and tells the agent where to resume.
 <rules>
   <do>Create clean TODO list for each epic</do>
   <do>Update epic state file BEFORE compaction</do>
+  <do>Execute stories IN ORDER as planned in epic file</do>
+  <do>Execute tasks within story ONE BY ONE (or parallel if independent)</do>
   <dont>Ask user for confirmation between stories — TODO is your guide</dont>
   <dont>Proceed to next story if review fails — enter fix loop</dont>
+  <dont>Reorder, skip, merge, or "optimize" story execution order</dont>
+  <dont>Combine tasks from different stories into one batch</dont>
+  <dont>Delegate entire story to @coder in one prompt — task by task only</dont>
 </rules>