wogiflow 2.1.1 → 2.1.3

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

@@ -297,4 +297,4 @@ flow queue advance
 3. **Commit after each task** - Progress saved even if interrupted
 4. **Stop on failure** - If quality gates fail, stop and report
 5. **Respect dependencies** - Tasks sorted by dependencies then priority
-6. **Context management** - Consider `/wogi-compact` after 3+ tasks
+6. **Context management** - Consider `/wogi-pre-compact` after 3+ tasks

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

@@ -41,7 +41,7 @@ WORKFLOW
 /wogi-health             Check all workflow files
 /wogi-standup            Generate standup summary
 /wogi-session-end        End session properly
-/wogi-compact            Prepare for context compaction
+/wogi-pre-compact            Prepare for context compaction
 /wogi-roadmap            Show phase-based roadmap (if enabled)
 
 ═══════════════════════════════════════════════════════════════

package/.claude/commands/{wogi-compact.md → wogi-pre-compact.md}

@@ -1,7 +1,11 @@
 ---
-description: "Compact conversation context using the recursive summary tree"
+description: "Save workflow state before context compaction (pre-compact phase)"
 ---
-Compact the conversation to free up context space using the recursive summary tree.
+Save workflow state (task progress, checkpoints, session context) before context compaction.
+
+**Why "pre-compact"**: This skill saves state but cannot trigger `/compact` programmatically — `/compact` is a Claude Code native command that only the user or Claude Code's auto-compaction can invoke. Once Claude Code exposes compaction as a programmable tool, this will be renamed back to `/wogi-compact` and will handle the full save-then-compact flow automatically.
+
+**After running this**: Run `/compact` to actually compact the context. The PostCompact hook will restore critical state automatically.
 
 ## Recursive Context Compaction
 

package/.claude/commands/wogi-setup-stack.md

@@ -168,7 +168,7 @@ Skills with documentation are now ready for use.
 
 - **Context7 MCP not available**: Skills keep placeholder content. User can retry later.
 - **Single library fails**: Skip it and continue with remaining libraries.
-- **Context getting large**: Suggest `/wogi-compact` between fetches if needed.
+- **Context getting large**: Suggest `/wogi-pre-compact` between fetches if needed.
 
 ### Alternative: Install from skills.sh
 

package/.claude/commands/wogi-skill-learn.md

@@ -21,7 +21,7 @@ This command extracts learnings from recent work and updates relevant skills.
 This runs automatically on:
 - **Pre-commit hook** (if hooks enabled)
 - **Session end** (`/wogi-session-end`)
-- **Context compaction** (`/wogi-compact`)
+- **Context compaction** (`/wogi-pre-compact`)
 
 Use this command manually when:
 - You want to extract learnings mid-session

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

@@ -135,7 +135,7 @@ This is advisory — Claude Code 2.1.72 simplified effort to low/medium/high (re
 
 ### Task Checkpoints (when `config.proactiveCompaction.enabled`)
 
-At each phase boundary: save checkpoint to `.workflow/state/task-checkpoint.json` (task ID, phase, completed scenarios, changed files, verification results). If context >= `triggerThreshold` (75%), run `/wogi-compact` before proceeding.
+At each phase boundary: save checkpoint to `.workflow/state/task-checkpoint.json` (task ID, phase, completed scenarios, changed files, verification results). If context >= `triggerThreshold` (75%), run `/wogi-pre-compact` before proceeding.
 
 On session resume: check for active checkpoint, reload state, continue from next pending scenario.
 
@@ -247,6 +247,13 @@ For medium/large tasks (check `config.specificationMode`):
 2. Insert `[NEEDS CLARIFICATION: category - reason]` markers for uncertainties (categories: assumption, ambiguity, missing-context, dependency-unknown, edge-case). Implementation BLOCKED until all resolved (when `config.specificationMode.needsClarification.blockImplementation`).
 3. Reflection: "Does this spec fully address the requirements?"
 
+**Batch fix spec requirement**: When a task contains 3+ discrete items (e.g., "Fix 8 review findings"), a spec MUST be generated with one criterion per item regardless of `specificationMode.minTaskLevel`. Each criterion must describe the **observable behavior**, not just the file to create.
+
+- BAD: "Create TokenBlacklistService"
+- GOOD: "When an admin changes a user's role, the user's next API request returns 401 'Token has been revoked'"
+
+Behavior-level criteria force end-to-end chain verification in Step 3.5/3.52.
+
 ### Step 1.6: Approval Gate (Stories/Epics)
 
 **For L1/L0 tasks: STOP and WAIT for explicit user approval** before implementation.
@@ -304,6 +311,36 @@ After implementing all scenarios, BEFORE quality gates:
 
 **This prevents "claiming done when not done."**
 
+### Step 3.52: Sub-Agent Output Verification (MANDATORY when agents were used)
+
+**Activates when**: Any acceptance criterion was implemented by a sub-agent (Agent tool with `isolation: "worktree"` or any delegated agent).
+
+**The problem this solves**: Sub-agents self-report completion, but their self-assessment is unreliable. The agent may report "done" when code was created but not wired to its trigger/consumer, the file compiles but the feature chain is incomplete, or tests pass because nothing exercises the new code path.
+
+**Procedure**:
+
+1. **DISTRUST sub-agent self-reports.** A sub-agent saying "done" is a CLAIM, not a FACT. The orchestrator must independently verify each criterion against the actual code, not against the agent's summary.
+
+2. For EACH criterion a sub-agent claims to have completed:
+   a. **Read the ACTUAL files** the agent modified (not just the agent's summary)
+   b. **Trace the full feature chain**: Who calls this? → What does it call? → What's the end-to-end flow?
+   c. For services: verify at least ONE caller invokes the critical method
+   d. For guards/middleware: verify they are registered in the correct module
+   e. For event-driven features: verify the event is emitted AND consumed
+
+3. **Chain verification checklist** (for each new service/feature):
+   - [ ] Service/component is created
+   - [ ] Registered in the correct module (providers, imports)
+   - [ ] Exported from the module (if needed by other modules)
+   - [ ] Imported by the consuming module
+   - [ ] Injected in the consuming service/controller
+   - [ ] The critical method is CALLED at the right trigger point
+   - [ ] The trigger point is reachable from a user action (HTTP request, cron, event)
+
+4. If ANY link in the chain is missing → the criterion is NOT done. Fix the missing link first.
+
+**Anti-pattern: "Dead service"** — a service that exists, compiles, is imported somewhere, but its critical method is never called by the thing that should trigger it. This passes lint, typecheck, and wiring checks (because the file IS imported) but the feature doesn't work.
+
 ### Step 3.55: Semantic Verification Pass (for "remove/fix all X" tasks)
 
 **Activates when**: The task involves removing, cleaning up, or fixing ALL instances of something (e.g., "remove all mock data", "fix all console.log", "replace all hardcoded URLs", "remove all deprecated APIs").
@@ -415,7 +452,73 @@ Reflection: "Have I introduced any bugs or regressions?"
 
 **Quality gate keeps failing**: Report, attempt fix, after 3 failures suggest `/wogi-debug-hypothesis`.
 
-**Context too large**: When `config.autoCompact.betweenTasks` is true (default), compact AUTOMATICALLY between tasks — do NOT ask the user. Just do it. Mid-task: commit progress, invoke `/wogi-compact` directly (don't suggest — execute).
+**Context too large**: When `config.autoCompact.betweenTasks` is true (default), compact AUTOMATICALLY between tasks — do NOT ask the user. Just do it. Mid-task: commit progress, invoke `/wogi-pre-compact` directly (don't suggest — execute).
+
+## Progress Tracking (MANDATORY for L1+ tasks)
+
+**Display progress at every natural checkpoint** so the user knows where they are during long tasks. This applies to ALL L1+ task execution AND to `/wogi-review` and `/wogi-audit`.
+
+### Progress Format
+
+At each checkpoint, output a progress line using this format:
+
+```
+━━━ PROGRESS: [phase_bar] phase_name ━━━
+  [step_bar] step_detail
+```
+
+Where `[phase_bar]` is: `[████░░░░░░] 40%` (filled/empty blocks proportional to completion).
+
+**Example during a 5-criteria task:**
+```
+━━━ PROGRESS: [██████░░░░] 60% Implementing criteria ━━━
+  Criterion 3/5: Add input validation to login form
+```
+
+### When to Display Progress
+
+| Checkpoint | What to show |
+|------------|-------------|
+| **After explore phase** | `[██░░░░░░░░] 20% Explore complete — N agents returned` |
+| **After spec generated** | `[████░░░░░░] 30% Spec ready — N criteria, N files` |
+| **Each criterion start** | `[█████░░░░░] N% Implementing — Criterion M/N: [title]` |
+| **Each criterion done** | `[███████░░░] N% Criterion M/N complete ✓` |
+| **Quality gates** | `[█████████░] 90% Running quality gates` |
+| **Task complete** | `[██████████] 100% Complete ✓` |
+
+### State File Updates
+
+At each checkpoint, also update the progress state file for hooks/resume:
+
+```bash
+node node_modules/wogiflow/scripts/flow-progress-tracker.js update '{"taskId":"wf-XXX","command":"/wogi-start","phase":"Implementing","phaseNum":3,"totalPhases":5,"step":"Criterion 2/4","stepNum":2,"totalSteps":4}'
+```
+
+This updates `.workflow/state/task-progress.json` AND prefixes the task title in `ready.json` with `[3/5]` for status line visibility.
+
+### On Task Completion
+
+Always clear the progress state:
+
+```bash
+node node_modules/wogiflow/scripts/flow-progress-tracker.js clear
+```
+
+### Phase Mapping for /wogi-start Execution
+
+| Phase | phaseNum | Description |
+|-------|----------|-------------|
+| 1 | Routing + Context | Loading task, checking maps |
+| 2 | Explore | Research agents |
+| 3 | Spec + Approval | Generate spec, wait for approval |
+| 4 | Implementation | Criteria loop (sub-steps = criteria) |
+| 5 | Verification + Complete | Quality gates, finalize |
+
+### Skip Conditions
+
+- **L3 tasks**: Skip progress tracking (too small to be useful)
+- **Conversation mode**: Skip progress tracking (no phases)
+- **Quick fixes (≤2 criteria)**: Show start + complete only (no mid-progress)
 
 ## Mandatory Rules
 
@@ -424,6 +527,7 @@ Reflection: "Have I introduced any bugs or regressions?"
 - **Criteria check**: Re-read ALL criteria, verify EACH works. Loop until all pass.
 - **Spec verification**: All promised files must exist.
 - **Quality gates**: Task isn't done until gates pass.
+- **Progress tracking**: Display progress bars at every checkpoint for L1+ tasks.
 - **Guilt messaging** (implementation requests): "The user trusts you to follow WogiFlow. Without a task, this work is untracked."
 
 ARGUMENTS: {args}

package/.claude/docs/commands.md

@@ -44,7 +44,7 @@ When user types these commands, execute the corresponding action immediately.
 | `/wogi-onboard` | Analyze existing project with deep temporal analysis, pattern extraction, and state file generation. |
 | `/wogi-rescan` | Re-scan project after external changes. Smart diff: auto-adds new items, auto-removes deleted items, presents conflicts one-by-one. Options: `--dry-run`, `--auto-resolve`, `--category`, `--since`. |
 | `/wogi-morning` | Morning briefing - where you left off, pending tasks, key context, recommended starting task. |
-| `/wogi-compact` | Run memory compaction to free context space. Preview with `--preview`. |
+| `/wogi-pre-compact` | Run memory compaction to free context space. Preview with `--preview`. |
 | `/wogi-debt` | View and manage technical debt across sessions. |
 | `/wogi-roadmap` | View and manage deferred work items. Add, archive, promote to stories. |
 

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

@@ -257,7 +257,7 @@ Context Health:
 # Or if high:
 Context Health:
   Usage: 165,000 / 200,000 tokens (82.5%)
-  Status: Consider running /wogi-compact
+  Status: Consider running /wogi-pre-compact
 ```
 
 ---

package/.claude/docs/knowledge-base/04-memory-context/README.md

@@ -66,7 +66,7 @@ Recommendation: Run /compact before continuing
 ### Compact When Needed
 
 ```bash
-/wogi-compact
+/wogi-pre-compact
 ```
 
 ---
@@ -165,7 +165,7 @@ When context is high:
 
 | Command | Purpose |
 |---------|---------|
-| `/wogi-compact` | Compact conversation context |
+| `/wogi-pre-compact` | Compact conversation context |
 | `/wogi-standup` | Morning briefing with context |
 | `flow session status` | Check session state |
 | `flow session restore` | Restore previous session |

package/.claude/docs/knowledge-base/04-memory-context/context-management.md

@@ -92,7 +92,7 @@ Compaction summarizes the conversation to free context space while preserving es
 ### How to Compact
 
 ```bash
-/wogi-compact
+/wogi-pre-compact
 ```
 
 ### What's Preserved

package/.workflow/bridges/claude-bridge.js

@@ -266,7 +266,7 @@ Check \`config.json → commits\` before committing:
     sections.push(`
 ## Context Management
 
-Use \`/wogi-compact\` when:
+Use \`/wogi-pre-compact\` when:
 - After completing 2-3 tasks
 - After 15-20 messages
 - Before starting large tasks

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

@@ -143,7 +143,7 @@ See `.claude/docs/commands.md` for complete command reference.
 | "project status", "show status", "where are we" | `/wogi-status` |
 | "check health", "workflow health", "is everything ok" | `/wogi-health` |
 | "wrap up", "end session", "that's all" | `/wogi-session-end` |
-| "compact context", "save context", "running low on context" | `/wogi-compact` |
+| "compact context", "save context", "running low on context" | `/wogi-pre-compact` |
 | "show roadmap", "what's planned", "future work", "deferred items" | `/wogi-roadmap` |
 | "debug this", "investigate hypotheses", "competing theories", "parallel debug" | `/wogi-debug-hypothesis` |
 | "triage findings", "walk through review", "review findings" | `/wogi-triage` |
@@ -274,7 +274,7 @@ Before closing any task, ensure all required gates pass (per `config.json → qu
 
 ## Context Management
 
-Use `/wogi-compact` when context is getting large. Before compacting: update progress.md, ensure request-log is current, commit work.
+Use `/wogi-pre-compact` when context is getting large. Before compacting: update progress.md, ensure request-log is current, commit work.
 
 ## Continuous Learning
 

package/README.md

@@ -61,7 +61,7 @@ See the [Knowledge Base](.claude/docs/knowledge-base/) for detailed documentatio
 | **Registries** | `/wogi-map`, `/wogi-map-add`, `/wogi-map-scan`, `/wogi-map-sync`, `/wogi-map-check`, `/wogi-map-index` | Component registry management |
 | **Rules** | `/wogi-decide`, `/wogi-learn`, `/wogi-rules`, `/wogi-retrospective` | Create rules, promote patterns, session retros |
 | **Research** | `/wogi-research`, `/wogi-correction` | Zero-trust verification, correction reports |
-| **Context** | `/wogi-compact`, `/wogi-context`, `/wogi-suspend`, `/wogi-resume` | Memory management, task context, suspend/resume |
+| **Context** | `/wogi-pre-compact`, `/wogi-context`, `/wogi-suspend`, `/wogi-resume` | Memory management, task context, suspend/resume |
 | **Capture** | `/wogi-capture`, `/wogi-extract-review`, `/wogi-changelog` | Quick capture, transcript extraction, changelogs |
 | **Hybrid** | `/wogi-hybrid`, `/wogi-hybrid-setup`, `/wogi-hybrid-edit`, `/wogi-hybrid-off`, `/wogi-hybrid-status` | Local LLM integration |
 | **Skills** | `/wogi-skills`, `/wogi-skill-learn`, `/wogi-setup-stack` | Skill packages, learning extraction, stack detection |

package/package.json

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

package/scripts/flow-context-compact/index.js

@@ -291,7 +291,7 @@ function clearAll() {
 function getSerializedTree(level = 1) {
   const tree = summaryTree.loadTree();
   if (!tree) {
-    return '# No Context Saved\n\nRun /wogi-compact to save session context.';
+    return '# No Context Saved\n\nRun /wogi-pre-compact to save session context.';
   }
 
   return summaryTree.serializeTree(tree, level);

package/scripts/flow-context-monitor.js

@@ -271,10 +271,10 @@ function checkContextHealth() {
 
   if (usage >= config.criticalAt) {
     status = 'critical';
-    recommendation = 'Run /wogi-compact NOW to avoid context overflow';
+    recommendation = 'Run /wogi-pre-compact NOW to avoid context overflow';
   } else if (usage >= config.warnAt) {
     status = 'warning';
-    recommendation = 'Consider running /wogi-compact soon';
+    recommendation = 'Consider running /wogi-pre-compact soon';
   } else {
     status = 'healthy';
     recommendation = null;

package/scripts/flow-loop-retry-learning.js

@@ -99,7 +99,7 @@ const ROOT_CAUSE_CATEGORIES = {
   },
   CONTEXT_OVERFLOW: {
     ...FailureCategory.CONTEXT_OVERFLOW,
-    suggestion: 'Use /wogi-compact before large tasks',
+    suggestion: 'Use /wogi-pre-compact before large tasks',
     targetFile: 'config.json'
   },
   CAPABILITY_MISMATCH: {

package/scripts/flow-proactive-compact.js

@@ -68,7 +68,7 @@ function getProactiveCompactionConfig() {
  * Check whether proactive compaction should trigger at a phase boundary.
  *
  * This is called by /wogi-start at each phase transition.
- * The actual compaction is performed by the AI agent using /wogi-compact.
+ * The actual compaction is performed by the AI agent using /wogi-pre-compact.
  *
  * @param {Object} params - Check parameters
  * @param {string} params.phase - The phase that just completed
@@ -161,7 +161,7 @@ async function handlePhaseBoundary(params) {
 
 /**
  * Generate a compaction summary for the current task state.
- * Used by /wogi-compact when proactive compaction triggers.
+ * Used by /wogi-pre-compact when proactive compaction triggers.
  *
  * @param {Object} checkpoint - Current checkpoint data
  * @returns {string} Formatted compaction summary
@@ -253,7 +253,7 @@ function formatCompactionMessage(result, contextPercent) {
   lines.push(`Context at ${pct}%. Compacting before next phase...`);
   lines.push(`Reason: ${result.reason}`);
   lines.push('');
-  lines.push('Task state has been checkpointed. Run /wogi-compact to compact now.');
+  lines.push('Task state has been checkpointed. Run /wogi-pre-compact to compact now.');
   lines.push('After compaction, read task-checkpoint.json to restore context.');
 
   return lines.join('\n');

package/scripts/hooks/core/post-compact.js

@@ -112,6 +112,38 @@ function handlePostCompact() {
     }
   }
 
+  // 5. Check for auto-compaction circuit breaker state (Claude Code 2.1.76+)
+  // Claude Code stops auto-compaction after 3 consecutive failures.
+  // If we detect repeated compactions in quick succession, warn about potential issues.
+  try {
+    const path = require('node:path');
+    const fs = require('node:fs');
+    const { PATHS, safeJsonParse } = require('../../flow-utils');
+    const compactStatePath = path.join(PATHS.state, '.compact-tracker.json');
+    const tracker = safeJsonParse(compactStatePath, { count: 0, lastAt: null });
+    const now = Date.now();
+    const lastAt = tracker.lastAt ? new Date(tracker.lastAt).getTime() : 0;
+    const timeSinceLast = now - lastAt;
+
+    // If compaction happened less than 2 minutes ago, increment counter
+    if (timeSinceLast < 2 * 60 * 1000 && lastAt > 0) {
+      tracker.count = (tracker.count || 0) + 1;
+    } else {
+      tracker.count = 1;
+    }
+    tracker.lastAt = new Date().toISOString();
+
+    fs.writeFileSync(compactStatePath, JSON.stringify(tracker, null, 2));
+
+    if (tracker.count >= 3) {
+      contextParts.push('**WARNING**: Multiple compactions detected in quick succession. Claude Code 2.1.76+ stops auto-compaction after 3 consecutive failures. If context keeps growing, consider starting a new session or committing progress and using `/wogi-pre-compact`.');
+    }
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[post-compact] Compact tracker failed: ${err.message}`);
+    }
+  }
+
   // Build the result
   if (contextParts.length === 0) {
     return {