wogiflow 2.12.0 → 2.15.0

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

@@ -160,6 +160,19 @@ Estimate if task fits in remaining context using `flow-context-estimator.js`:
 - Count criteria (~3% each), files (~2% each), refactor buffer (+10%)
 - If `projected_total > 95%` → compact first. If `current >= 90%` → emergency compact.
 
+### Step 0.3: Intent Bootstrap (when `config.intentGroundedReasoning.enabled`)
+
+**Conditional** — runs only when the IGR master flag is on AND no intent artifacts exist yet in `.workflow/state/`.
+
+First run per project with IGR enabled, present the Option C three-choice prompt (see `.claude/docs/intent-grounded-reasoning.md` for the exact UX):
+- `[1]` Bootstrap now (blocks ~5-10 min)
+- `[2]` Bootstrap in background, review at `/wogi-session-end` (default)
+- `[3]` Skip for now (3 consecutive skips silences the prompt)
+
+Run via `node scripts/flow-intent-bootstrap.js bootstrap [--auto-confirm]`. Scaffolds 4 artifacts (`product.md`, `domain-model.md`, `user-journeys.md`, `glossary.md`) with `reviewStatus: draft`. The trap-zone detector runs agnostic structural-ambiguity scanning.
+
+When IGR flag is OFF: this step is SKIPPED entirely. Pipeline proceeds to Step 0.5 with no overhead.
+
 ### Step 0.5: Parallel Execution Check
 
 Check `ready.json` for 2+ tasks. If parallelizable (no dependencies), offer parallel execution with worktree isolation.
@@ -171,915 +184,32 @@ Check `ready.json` for 2+ tasks. If parallelizable (no dependencies), offer para
 3. Check `app-map.md`, `function-map.md`, `api-map.md`, `decisions.md`
 4. Auto-invoke matched skills based on task context
 
-### Decision Authority Framework (Cross-Cutting — applies to ALL steps)
-
-**Before presenting ANY decision to the user**, classify it using `flow-decision-authority.js`:
-
-```bash
-node node_modules/wogiflow/scripts/flow-decision-authority.js classify "<decision text>"
-```
-
-| Authority Level | Action |
-|-----------------|--------|
-| `agent-decides` | Decide autonomously. Report in completion summary only. |
-| `agent-decides-report-after` | Decide autonomously. Explicitly state the decision after implementing. |
-| `owner-decides` | Present to user. Wait for answer before proceeding. |
-| `auto-fix-report-after` | Fix automatically. Report what was fixed after. |
-
-**Batch enforcement**: When multiple decisions arise in a single task, use `batchClassify()`. If owner-decides questions exceed `maxOwnerQuestionsPerBatch` (default: 5), overflow is automatically downgraded to `agent-decides-report-after`. This prevents question flooding (12+ questions in one batch).
-
-**Default categories**: engineering → agent-decides, infrastructure → agent-decides-report-after, productBehavior → owner-decides, security → auto-fix-report-after, ux → owner-decides, naming → agent-decides, performance → agent-decides-report-after.
-
-**User can update**: Via `/wogi-decide "from now on, just fix [category] yourself"` which calls `updateCategoryAuthority()` to change the config.
-
-**Low-confidence classification**: When the classifier cannot confidently categorize a decision, it defaults to `owner-decides` (safest fallback).
-
-### Step 1.2: Clarifying Questions
-
-Before generating specs (skip for small tasks ≤2 files, bugfixes, explicit specs):
-- Scope validation, assumption surfacing, edge cases, integration points
-- Config: `config.clarifyingQuestions`
-
-### Step 1.25: Item Reconciliation Gate (Multi-Item Inputs)
-
-**Activates when**: User input contains 3+ discrete requests (identified by: numbered lists, bullet points, "and also", "plus", semicolons separating requests, or distinct topics in voice-transcribed text).
-
-**Purpose**: Prevent item loss when the AI compresses many requests into fewer stories. This is the #1 cause of "silently dropped items" in long inputs.
-
-**Procedure**:
-1. **Enumerate**: Produce a numbered checklist of EVERY discrete request from the user's input. Each item = one testable action. No compression, no grouping, no summarization.
-2. **Confirm count**: Display the checklist and count: "I found N items in your request: [list]. Is this complete?"
-3. **Map to work items**: Each checklist item becomes a trackable acceptance criterion. Items may be grouped into stories, but EVERY item must appear as a criterion in at least one story. No item may be dropped during grouping.
-4. **Reconciliation check**: After stories/tasks are created, cross-reference: for each original checklist item, verify it appears in at least one acceptance criterion. If any item is missing → add it before proceeding.
-5. **At completion** (Step 3.5): The criteria verification must trace back to this original checklist. Every checklist item must be verified as implemented.
-
-**Example**:
-```
-User: "Fix the login page, add forgot password, remove mock data,
-       update the header logo, and add loading states to all forms"
-
-Item Reconciliation:
-  1. Fix the login page [→ Story A, criterion 1]
-  2. Add forgot password flow [→ Story A, criterion 2]
-  3. Remove all mock data [→ Story B, all criteria]
-  4. Update header logo [→ Story C, criterion 1]
-  5. Add loading states to all forms [→ Story C, criterion 2]
-
-  5 items found → 5 criteria across 3 stories → 0 items dropped ✓
-```
-
-**Skip when**: Input has only 1-2 items, or is a task ID reference.
-
-**ANTI-DEFERRAL ENFORCEMENT**: After reconciliation, verify ALL items became tasks/criteria. If you find yourself writing "deferred", "skipped", or "not created" for ANY item — STOP. You are violating the anti-deferral rule. The user provided these items for a reason. Create tasks for ALL of them. You may suggest priority ordering (P0-P3), but you must NEVER autonomously filter items out. A large ready queue is correct behavior. A filtered queue is data loss that breaks the user's trust.
-
-### Step 1.3: Explore Phase (MANDATORY Multi-Agent Research)
-
-**For L2+ tasks. Research is MANDATORY** — do NOT skip even if you think you know the answer.
-
-Before launching: check `.workflow/state/research-cache.json` for cached results (TTL: 24h).
-
-**Research Depth** (`config.planMode.researchDepth`):
-- `"thorough"`: All 5-6 agents in parallel
-- `"standard"`: Agents 1 + 2 + 4 (3 agents)
-- `"minimal"`: Agent 1 only
-
-**L3 (Subtask/trivial) tasks always skip this phase.**
-
-**Agents** (full prompts in `.claude/docs/explore-agents.md` — Read that file before launching):
-
-| Agent | Focus | Network |
-|-------|-------|---------|
-| 1. Codebase Analyzer | Related files, reusable components, dependency map, assumptions | Local |
-| 2. Best Practices | Current best practices, pitfalls, ecosystem patterns | Web |
-| 3. Version Verifier | API compatibility, deprecated APIs, version gotchas | Web |
-| 4. Risk & History | feedback-patterns, corrections, promoted rules, rejected approaches | Local |
-| 5. Standards Preview | Applicable rules, reuse candidates across ALL registries, security patterns | Local |
-| 6. Consumer Impact | **ALL L1+ tasks.** Map ALL consumers, classify BREAKING/NEEDS-UPDATE/SAFE. Write results to `.workflow/state/blast-radius-{taskId}.json` | Local |
-
-Launch all in parallel. When `config.hybrid.enabled`, route via `model` parameter (explore → sonnet, search → haiku, judging → opus).
-
-**After agents complete**: Display consolidated research summary covering codebase analysis, best practices, version info, risks, standards, and consumer impact.
-
-**REUSE GATE (MANDATORY)**: After consolidating agent results, check for reuse candidates:
-1. Collect all reuse candidates reported by Agent 1 (domain-keyword search) and Agent 5 (registry scan)
-2. If ANY reuse candidate has purpose overlap with planned new code → **STOP and present to user**:
-   - Show each candidate: name, path, purpose, similarity
-   - Ask: "Use existing / Extend existing / Create new (explain why)"
-   - Implementation BLOCKED until user decides on each candidate
-3. If no reuse candidates found → proceed normally
-4. This gate runs BEFORE spec generation — catching reuse early prevents wasted implementation
-
-**For L1/L0 tasks**: Offer to deepen research (exhaustive search, load all skills, full dependency tree).
-
-**Fallback**: If agents fail, log warning and proceed with remaining. Consumer Impact failure on L1+ tasks = HARD BLOCK (require user confirmation). See `.claude/docs/explore-agents.md` for details.
-
-**Constraints**: READ-ONLY phase. No Edit/Write. Agents use only Glob, Grep, Read, WebSearch, WebFetch.
-
-### Step 1.45: Scope-Confidence Gate (L0/L1 tasks only)
-
-**Activates when**: Task level is L0 or L1. Skip for L2/L3 tasks.
-
-**The problem this solves**: Multi-day plans often depend on assumptions about what exists (new tables, new models, new APIs, new services). Without verification, a 7-10 day plan can collapse to 1 day when a single question reveals the assumption was wrong. This gate audits scope-inflating assumptions BEFORE the spec is generated — not the same as clarifying questions (Step 1.2) which target user intent.
-
-**Procedure**:
-
-1. **Extract assumptions**: From the explore phase results and task description, list every assumption the plan depends on:
-   - New database tables/schemas needed
-   - New API endpoints or services to create
-   - New models or data structures
-   - External integrations assumed not to exist
-   - Infrastructure components (queues, caches, workers)
-
-2. **Verify each assumption against the codebase**:
-   - For each assumption, grep/glob for existing implementations
-   - Check schema files, migration files, service directories, API routes
-   - Check `app-map.md`, `function-map.md`, `api-map.md`, `schema-map.md` for registered components
-
-3. **Classify results**:
-   | Status | Meaning | Action |
-   |--------|---------|--------|
-   | VERIFIED | Assumption confirmed by codebase evidence | Proceed — scope is accurate |
-   | EXISTS | Assumed-new thing already exists | **Scope reduction** — remove from plan |
-   | UNVERIFIABLE | Cannot confirm or deny from codebase | **Ask user** before proceeding |
-   | CONTRADICTED | Codebase shows opposite of assumption | **Scope change** — replan required |
-
-4. **Present findings to user** (MANDATORY when any UNVERIFIABLE or CONTRADICTED found):
-   ```
-   ━━━ SCOPE-CONFIDENCE AUDIT ━━━
-   Task: [title]
-
-   Assumptions verified:
-     ✓ [assumption] — found at [file:line]
-
-   Scope reductions (already exists):
-     ↓ [assumption] — exists at [file:line], removing from plan
-
-   Needs confirmation:
-     ? [assumption] — does [X] already exist? Could not find in codebase.
-
-   Contradictions:
-     ✗ [assumption] — codebase shows [opposite evidence]
-
-   Revised estimate: [original] → [adjusted based on findings]
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   ```
-
-5. **Wait for user response** on UNVERIFIABLE items before proceeding to spec generation. Spec MUST reflect verified scope, not assumed scope.
-
-**This is NOT the same as Step 1.2 (Clarifying Questions)**:
-- Step 1.2 targets **user intent** ("what do you want?")
-- Step 1.45 targets **scope assumptions** ("what does the codebase already have?")
-- Step 1.2 runs before explore; Step 1.45 runs after explore (uses explore results)
-
-### Step 1.5: Generate Specification
-
-For medium/large tasks (check `config.specificationMode`):
-
-1. Generate spec to `.workflow/specs/wf-XXXXXXXX.md`:
-   - Acceptance criteria (Given/When/Then), implementation steps, files to change
-   - Boundary declarations (files that must NOT be modified)
-   - Consumer impact plan (for refactors — MANDATORY if BREAKING consumers found; 5+ = phased approach required)
-   - Test strategy, verification commands
-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.
-Approval phrases: approved, proceed, looks good, lgtm, go ahead, yes, continue, start.
-L2/L3 skip this gate.
-
-### Step 1.7: Test Generation (when `config.testing.enabled` and `config.testing.generation.autoGenerate`)
-
-When testing is enabled and auto-generation is on:
-1. Run `node node_modules/wogiflow/scripts/flow-test-generate.js wf-XXXXXXXX` to parse spec and generate test scaffolds
-2. Review output: number of test files created, criteria coverage, edge cases
-3. If tests were generated, add "Make generated tests pass" to TodoWrite items in Step 2
-4. During implementation (Step 3), verify generated tests fail before implementation and pass after
-5. If `testing.generation.autoGenerate: false` or `testing.enabled: false`, skip this step entirely
-
-### Step 2: Decompose into TodoWrite
-
-Each acceptance criterion → TodoWrite item. Also add: update request-log, update maps, run quality gates, commit.
-
-### Step 2.5: TDD Mode Check
-
-When `config.tdd.enforced` is true OR `--tdd` flag is used, the execution loop switches to test-first order. Also auto-enables for task types listed in `config.tdd.defaultForTypes` (e.g., `["bugfix"]`).
-
-**TDD Execution Loop** (replaces normal Step 3 when active):
-
-For each acceptance criterion:
-1. Mark in_progress in TodoWrite
-2. **Write test** for this criterion (Given/When/Then → test assertion)
-3. **Run test → MUST FAIL** (proves test is meaningful). If it passes before implementation → WARNING: test may be trivial
-4. **Implement** the feature/fix following matched skill patterns
-5. **Run test → MUST PASS**. If still fails → debug and fix (max 5 retries)
-6. **Run full verification** (lint, typecheck, all tests)
-7. **Save TDD artifact** to `.workflow/verifications/` with before/after test results
-8. Mark completed only when all tests pass
-
-Test framework auto-detected from package.json: jest, vitest, mocha, tap, or fallback `node --test`.
-
-### Step 3: Execute Each Scenario (Loop)
-
-**When TDD is NOT active**, use this normal flow. For each acceptance criterion:
-1. Mark in_progress in TodoWrite
-2. Implement following matched skill patterns
-3. Run verification (lint, typecheck, tests) → save artifact to `.workflow/verifications/`
-4. If failing: debug, fix, retry (max 5 attempts)
-5. Mark completed only when verification passes
-
-### Step 3.05: Sprint-Based Context Reset (L1+ tasks with 5+ criteria)
-
-**Activates when**: `config.sprintReset.enabled` (default: true) AND task has 5+ acceptance criteria AND current criterion index is a multiple of `config.sprintReset.criteriaPerSprint` (default: 3).
-
-**The problem this solves**: For large tasks, context fills with implementation details from early criteria. By criterion 6+, the AI is working with degraded context — old diffs, stale tool results, and exploration artifacts crowd out what matters for the current criterion. The Anthropic harness design research found that full context resets with structured file-based handoffs produce higher quality output than continuous context for long-running tasks.
-
-**Procedure** (runs automatically at sprint boundaries):
-
-1. After completing criterion N (where N % `criteriaPerSprint` === 0 AND remaining criteria > 0):
-2. **Commit progress**: `git add -A && git commit -m "sprint: criteria 1-N of M complete"`
-3. **Save sprint checkpoint** to `.workflow/state/task-checkpoint.json`:
-   - Task ID, spec path, completed criteria indices, changed files, remaining criteria
-4. **Output sprint summary** (visible to user):
-   ```
-   ━━━ SPRINT BOUNDARY ━━━
-   Completed criteria 1-N of M. Committing and resetting context.
-   Remaining: criteria (N+1)-M
-   ```
-5. **Compact context** — this triggers a full compaction. The PostCompact hook restores:
-   - Active task ID and spec reference
-   - Which criteria are done vs pending (from checkpoint)
-   - Changed files list
-6. **Resume from checkpoint** — read the spec fresh, skip completed criteria, continue with criterion N+1
-
-**Why this is different from normal compaction**: Normal compaction summarizes the conversation. Sprint reset goes further — it commits work, saves a structured checkpoint, and compacts. The next sprint starts with a clean slate + the checkpoint file, not a compressed summary of everything that happened. The AI reads the spec fresh rather than relying on a summarized memory of it.
-
-**Configuration**:
-```json
-{
-  "sprintReset": {
-    "enabled": true,
-    "criteriaPerSprint": 3,
-    "minTaskCriteria": 5
-  }
-}
-```
-
-**Skip when**: Task has < 5 criteria, TDD mode is active (TDD has its own rhythm), or `sprintReset.enabled` is false.
-
-### Step 3.5: Criteria Completion Verification (MANDATORY)
-
-After implementing all scenarios, BEFORE quality gates:
-
-1. Re-read original acceptance criteria from spec
-2. For EACH criterion: verify it was actually implemented and WORKS (not just "code exists" but "code does what the criterion describes")
-3. If ANY criterion NOT done → implement it, then re-check ALL criteria again
-4. Only proceed when ALL criteria verified
-
-**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: Inventory-Based Verification (for "remove/fix/replace all X" tasks)
-
-**Activates when**: The task involves removing, cleaning up, fixing, or replacing ALL instances of something (e.g., "remove all mock data", "fix all console.log", "replace all hardcoded URLs", "remove all deprecated APIs").
-
-**The problem this solves**: Pattern-based search (grep, regex) only finds instances that match a naming convention. Semantic variants — inline hardcoded arrays, helper functions that wrap the target, useState initializers with fake data, constants not named with the expected prefix — are invisible to pattern search. In practice, pattern search finds ~60-70% of instances. The AI then declares "done" and the remaining 30-40% persist undetected. This has caused repeated false completions (3-4x on a single project).
-
-**Core principle**: For each file in scope, ask **"does anything in this file serve the PURPOSE of [what we're removing]?"** — regardless of what it's named. Reason about function, not strings.
-
-**Procedure (3 phases — ALL mandatory)**:
-
-#### Phase A: Pre-Implementation Inventory (BEFORE any code changes)
-
-1. **Identify all files in scope** — every file that could contain instances of [X]. Use both:
-   - Pattern search (grep/glob) for syntactic matches
-   - File-by-file reading of components/pages/modules that CONSUME data related to [X]
-
-2. **For each file, answer the semantic question**: "Does anything in this file serve the purpose of [what we're removing]?" Examples by task type:
-
-   | Task Type | Semantic Question | What Pattern Search Misses |
-   |-----------|-------------------|---------------------------|
-   | Remove mock data | "Where does this component get its displayed data? Is it from an API call or a local constant/array/useState?" | Inline arrays (`const customers = [{...}]`), useState initializers (`useState([...POLICY_DATA])`), export constants not named `MOCK_*` |
-   | Remove console.log | "What in this file produces output to any channel?" | `console.warn`, `console.debug`, `debugger`, `alert()`, custom logger wrappers |
-   | Replace hardcoded URLs | "What string values in this file resolve to network addresses?" | URLs built from concatenation, template literals, env var fallbacks with hardcoded defaults |
-   | Remove deprecated API | "What in this file provides the same FUNCTIONALITY as the deprecated API?" | Wrapper functions, polyfills, compatibility shims, re-implementations |
-   | Fix all raw JSON.parse | "What in this file deserializes JSON?" | Utility functions that call JSON.parse internally, library wrappers |
-
-3. **Trace data-providing imports one level (MANDATORY)**:
-
-   The semantic scan in step 2 catches inline instances but gives a free pass to imported values. Imported constants, configurations, and helpers can contain the exact thing you're looking for — hidden behind one level of indirection and a legitimate-sounding name (`DEFAULT_*`, `INITIAL_*`, `FALLBACK_*`, `BASE_*`).
-
-   **For every import statement in each scoped file**, classify it:
-
-   | Import Type | Example | Action |
-   |-------------|---------|--------|
-   | **Data-providing** | `import { RATE_OPTIONS } from './constants'` | MUST read the source file and apply the semantic question to its contents |
-   | **Utility/function** | `import { formatDate } from './utils'` | Skip — unless the function wraps or returns the target pattern |
-   | **Type/interface** | `import type { Customer } from './types'` | Skip — types don't contain runtime data |
-   | **Style/asset** | `import styles from './styles.module.css'` | Skip |
-   | **Component** | `import { Button } from './ui'` | Skip — unless it's a wrapper that embeds the target pattern |
-
-   **How to classify**: If the import provides a value that gets **rendered, displayed, logged, passed to an API, or used as configuration** — it's data-providing. Read its source.
-
-   **Anti-pattern — naming convention bias**: Constants named `DEFAULT_*`, `INITIAL_*`, `FALLBACK_*`, `CONFIG_*`, `BASE_*` look legitimate but are often hardcoded placeholders. The name is NOT evidence of legitimacy. Only the source is.
-
-   **Rule**: Any imported value that contributes to **user-visible output** and resolves to a hardcoded literal (not an API call, env var, or database query) is an instance of [X] — regardless of what it's named or which directory it lives in.
-
-4. **Produce a numbered inventory** and display it to the user:
-   ```
-   ━━━ PRE-IMPLEMENTATION INVENTORY ━━━
-   Found N instances of [X] across M files:
-
-     1. [file:lines] — [description] [TYPE: syntactic|semantic|import-traced]
-     2. [file:lines] — [description] [TYPE: syntactic|semantic|import-traced]
-     ...
-
-   Total: N instances (S syntactic, M semantic)
-   Confirm inventory is complete before proceeding? [Y/adjust]
-   ```
-
-5. **Wait for user confirmation** that the inventory is complete. If the user identifies missing items, add them. This step is CRITICAL — it commits the AI to a concrete scope that can be verified later.
-
-#### Phase B: Implementation
-
-6. Implement the removal/fix/replacement for EVERY item in the inventory. Each inventory item becomes a trackable unit of work.
-
-#### Phase C: Post-Implementation Re-Inventory (AFTER all changes)
-
-7. **Re-run the SAME semantic scan** from Phase A (including import tracing from step 3) on the SAME set of files. Do NOT downgrade to pattern-only search.
-
-8. **Diff the inventories**:
-   ```
-   ━━━ POST-IMPLEMENTATION VERIFICATION ━━━
-   Re-scanned M files for [X]:
-
-     1. [file:lines] — [description]          → REMOVED ✓
-     2. [file:lines] — [description]          → REMOVED ✓
-     3. [file:lines] — [description]          → STILL PRESENT ✗
-     ...
-
-   Result: N/N removed (0 remaining)
-   ```
-
-9. **If ANY items remain** → task is NOT done. Fix the remaining items and re-verify. Do NOT proceed to quality gates with remaining items.
-
-10. **If new instances are discovered** during re-scan (including via import tracing) that weren't in the original inventory → add them, fix them, and note them as "discovered during verification."
-
-**Why this works**: The inventory creates a concrete, numbered checklist BEFORE implementation. The AI cannot claim "done" when the post-inventory shows items still present — the evidence is in the conversation. The pre/post diff is unfakeable.
-
-**Skip conditions**: Tasks that target a specific file or a small known set (e.g., "remove the mock import in Dashboard.tsx") don't need the full inventory — they're scoped enough already. The inventory is for "all X" / "every X" / "clean up X everywhere" tasks.
-
-### Step 3.56: Skeptical Evaluator Gate (L2+ tasks, when `config.skepticalEvaluator.enabled`)
-
-**The problem this solves**: The same agent that wrote the code verifies its own work in Step 3.5. Anthropic's harness design research found that "separating the agent doing the work from the agent judging it proves to be a strong lever" and that "tuning standalone evaluators toward skepticism is far more tractable than making a generator critical of its own work." This is "confident praise bias" — the implementer always thinks it did a good job.
-
-**Activates when**: `config.skepticalEvaluator.enabled` (default: true) AND task level is L2 or higher (not L3 trivial tasks).
-
-**Procedure**:
-
-1. **Spawn a skeptical evaluator sub-agent** (separate from the implementation agent):
-   ```
-   Agent({
-     subagent_type: "code-reviewer",
-     model: "sonnet",  // Use a different model for diversity
-     prompt: <see below>
-   })
-   ```
-
-2. **Evaluator prompt** (tuned toward skepticism):
-   ```
-   You are a SKEPTICAL code evaluator. Your job is to find problems, not praise.
-   Assume the implementation has gaps until proven otherwise.
+### Decision Authority (Cross-Cutting)
 
-   ## Task Specification
-   <read and paste the spec from .workflow/specs/wf-XXXXXXXX.md>
+Classify decisions via `node node_modules/wogiflow/scripts/flow-decision-authority.js classify "<text>"`:
 
-   ## Implementation Diff
-   <git diff of all changed files>
+| Authority | Action |
+|-----------|--------|
+| `agent-decides` | Decide autonomously, report in summary |
+| `agent-decides-report-after` | Decide autonomously, state decision after |
+| `owner-decides` | Present to user, wait for answer |
+| `auto-fix-report-after` | Fix automatically, report what was fixed |
 
-   ## Your Job
-
-   For EACH acceptance criterion in the spec:
-   1. Read the criterion carefully
-   2. Find the EXACT code that implements it (cite file:line)
-   3. Grade: PASS (fully works), PARTIAL (code exists but incomplete), FAIL (not implemented)
-   4. If PARTIAL or FAIL: explain exactly what's missing
-
-   IMPORTANT: "Code exists" is NOT the same as "criterion is met."
-   A service that exists but is never called = FAIL.
-   A component that renders but doesn't handle the specified edge case = PARTIAL.
-   Only grade PASS when the criterion is FULLY satisfied end-to-end.
-
-   ## Output Format
-   Return JSON:
-   {
-     "criteria": [
-       { "criterion": "...", "grade": "PASS|PARTIAL|FAIL", "evidence": "file:line", "issue": "..." }
-     ],
-     "overallPass": true/false,
-     "criticalIssues": ["..."]
-   }
-   ```
-
-3. **Process evaluator results**:
-   - If `overallPass: true` → proceed to Step 3.6
-   - If `overallPass: false` → **iteration loop** (see below)
-
-4. **Generator-Evaluator Iteration Loop** (when evaluator finds issues):
-   - Feed the evaluator's `criticalIssues` and failed criteria back to the implementation context
-   - Fix the identified issues (targeted fixes, not re-implementation)
-   - Re-run the evaluator on the updated diff
-   - **Max iterations**: `config.skepticalEvaluator.maxIterations` (default: 3)
-   - If still failing after max iterations → proceed to Step 3.6 anyway but **flag the unresolved issues** in the completion report
-
-5. **Calibration** (when `config.skepticalEvaluator.calibration` is true):
-   - Before spawning the evaluator, check `.workflow/state/eval-calibration.json` for calibration examples
-   - If examples exist, inject 2-3 into the evaluator prompt as few-shot examples:
-     - One high-scoring example (what a PASS looks like)
-     - One low-scoring example (what a FAIL looks like)
-   - This prevents score drift — the evaluator is anchored to concrete examples
-
-**Configuration**:
-```json
-{
-  "skepticalEvaluator": {
-    "enabled": true,
-    "maxIterations": 3,
-    "model": "sonnet",
-    "calibration": true,
-    "skipForL3": true
-  }
-}
-```
-
-**Why this works**: The evaluator has NO emotional investment in the code. It reads the spec and the diff cold. It's explicitly prompted to be skeptical. And because it's a separate sub-agent, it has a fresh context — no accumulated "I already know this works" bias from the implementation phase.
-
-### Step 3.58: Runtime Verification Gate — Auto-Test Generation (MANDATORY)
-
-**Activates when**: ANY code file is changed. This is the DEFAULT — not optional.
-
-Run detection: `node node_modules/wogiflow/scripts/flow-runtime-verification.js task-type [changed-files...]`
-
-This returns the task type: `frontend`, `backend`, `fullstack`, or `other`. For `frontend` and `fullstack`, UI browser tests are generated. For `backend` and `fullstack`, API integration tests are generated. For `other`, standard static verification applies.
-
-**The problem this solves**: AI workers mark tasks as "done" based on static evidence (TypeScript compiles, build succeeds) without verifying the feature actually works end-to-end. This leads to repeated failed iterations. Auto-generated tests catch these failures BEFORE the user does.
-
-**DEFAULT BEHAVIOR**: For every task, WogiFlow auto-generates and runs verification tests as part of the execution loop. Tests are written to `tests/verification/` and persist as regression guards. This is ON by default — disable with `config.runtimeVerification.enabled: false`.
-
-#### Auto-Test Generation Flow
-
-```
-For EACH acceptance criterion in the spec:
-  1. Classify: Is this a UI behavior, API behavior, or internal logic?
-  2. Generate: Write a test that exercises the criterion
-  3. Implement: Write the actual code
-  4. Run: Execute the test — it MUST pass
-  5. If FAIL → debug, fix, re-run (max 5 retries)
-  6. Persist: Test file stays in tests/verification/ as regression guard
-```
-
-**This is NOT TDD** (where tests come first and must fail initially). This is **post-implementation verification** — the test is generated from the criterion, the code is written, then the test validates the code works. The key difference: TDD tests are written before code; verification tests are written alongside code and run after.
-
----
-
-#### FRONTEND: Browser Test Generation (Playwright + WebMCP)
-
-**Activates when**: Changed files match `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.css`, `*.styled.*`
-
-**The problem this solves**: AI workers mark UI tasks as "done" based on static evidence without ever opening a browser. (See: Pipeline Rules case study — 5 failed iterations, same bug.)
-
-**BANNED verification methods** — these NEVER count as evidence for UI tasks:
-
-| Banned Method | What it proves | Why it's insufficient |
-|---|---|---|
-| `grep` deployed bundle for function names | Code included in build | Function may never execute or render wrong |
-| `tsc --noEmit` passes | Types are correct | Type-correct code can have wrong runtime behavior |
-| `vite build` succeeds | Modules resolve | Build success says nothing about UX |
-| "I read the code and it's logically correct" | Nothing | Author is worst possible judge of own work |
-| `aws s3 sync` completes | Files hosted | Hosting ≠ functioning |
-
-**Evidence Tiers** — every verification claim must be classified:
-
-| Tier | Name | Sufficient alone? |
-|---|---|---|
-| 0 | STATIC (compile, build, lint) | NEVER |
-| 1 | STRUCTURAL (file exists, imported, route registered) | NEVER |
-| 2 | OBSERVATIONAL (page loads, feature renders) | Yes (display-only) |
-| 3 | INTERACTIVE (click/type/submit → observed result persists) | Yes (behavioral) |
-| 4 | AUTOMATED (Playwright/WebMCP test passes) | Yes (strongest) |
-
-**Minimum: Tier 2 for display criteria, Tier 3 for behavioral criteria.**
-
-#### Verification Method Selection
-
-Run: `node node_modules/wogiflow/scripts/flow-runtime-verification.js method`
-
-**Priority order** (use the first available):
-
-**1. WebMCP Browser Verification (DEFAULT — preferred)**
-
-When `config.webmcp.enabled` or a browser MCP server is detected in `.mcp.json`:
-
-For EACH acceptance criterion:
-1. Navigate to the affected page via `mcp_browser_navigate`
-2. Screenshot BEFORE: `mcp_browser_screenshot()`
-3. Perform the user action (click, type, select, submit)
-4. Wait 2-3 seconds for async updates
-5. Screenshot AFTER: `mcp_browser_screenshot()`
-6. Assert DOM state: `mcp_browser_evaluate("document.querySelector(...)")`
-7. Record in Behavioral Evidence Log
-
-**High-risk tasks** (state mutation detected — useMutation, invalidateQueries, onMutate):
-- After all criteria verified, wait 3 seconds
-- Screenshot again — check state persisted after refetch
-- Reload page: `mcp_browser_navigate` to same URL
-- Wait for networkidle
-- Screenshot — check state survived page reload
-- If state reverted → the server didn't persist, or refetch overwrote it → FAIL
-
-**2. Playwright Test Generation (secondary)**
-
-When Playwright/Puppeteer is in dependencies but no WebMCP:
-
-1. Auto-generate a Playwright test from acceptance criteria
-2. Write test to `tests/verification/verify-{taskId}.spec.ts`
-3. Instruct the user: "Run `npx playwright test tests/verification/verify-{taskId}.spec.ts --headed` to verify"
-4. If the project has CI, the test persists as a regression guard
-
-**3. User Verification Checklist (fallback — always available)**
-
-When neither WebMCP nor Playwright is available:
-
-Present a checklist to the user:
-```
-━━━ USER VERIFICATION CHECKLIST ━━━
-I cannot verify UI behavior from the CLI. Please check:
-
-□ 1. Navigate to [page]
-□ 2. [criterion 1 — specific action + expected result]
-□ 3. [criterion 2 — specific action + expected result]
-□ Wait 3 seconds after each action
-□ Refresh the page and verify changes persisted
-
-Reply "verified" when all checks pass, or describe what's broken.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**CRITICAL**: The agent MUST wait for the user's "verified" response before marking the task complete. Do NOT proceed to quality gates without verification.
-
-#### Behavioral Evidence Log (BEL)
-
-Before marking ANY UI task complete, produce a BEL:
-
-```
-━━━ BEHAVIORAL EVIDENCE LOG ━━━
-Task: wf-XXXXXXXX
-Method: WEBMCP / PLAYWRIGHT / USER_CHECKLIST
-Verified on: localhost:5173
-
-CRITERION: "[text]"
-  ACTION: Clicked "Route To" cell, selected "Design Department"
-  EXPECTED: Cell updates to show "Design DEPARTMENT"
-  OBSERVED: Cell shows "Design DEPARTMENT" with blue icon
-  WAIT: 3 seconds — state persisted after refetch
-  VERDICT: PASS
-  EVIDENCE: Tier 3 (INTERACTIVE)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-The OBSERVED field MUST describe what was SEEN, not what the code theoretically produces.
-
-#### Pre-Implementation "See Before You Touch" (modification tasks)
-
-For tasks modifying existing UI (not greenfield):
-1. Start dev server if not running
-2. Navigate to the affected page
-3. Screenshot/observe current state (BEFORE)
-4. Document the baseline
-5. Then implement changes
-6. After implementation, compare BEFORE vs AFTER
-
-#### Repeat Failure Protocol (Groundhog Day Detector)
-
-When the SAME issue is reported in 2+ consecutive dispatches:
-
-| Strike | Action |
-|--------|--------|
-| 1 | Normal fix + BEL |
-| 2 | MANDATORY root cause analysis BEFORE coding. Change approach. Add console.log tracing. Tier 3+ evidence required. |
-| 3 | HARD BLOCK: Cannot mark done without screenshot/console evidence. Must state what's DIFFERENT this time. |
-| 4+ | ESCALATION: Acknowledge inability, suggest pair debugging with user. |
-
-Run: `node node_modules/wogiflow/scripts/flow-runtime-verification.js repeat wf-XXXXXXXX`
-
-#### Devil's Advocate Prompt
-
-Before marking ANY task complete (frontend or backend), ask yourself:
-
-> "Assume this is broken. What are the 3 most likely ways it could fail?"
-
-Then CHECK each one:
-1. Does the API actually accept these fields? (curl it or check the DTO)
-2. Does the response include the fields I'm reading? (log the response)
-3. Does the UI update persist after refetch/re-render? (wait 3 seconds and look again)
-4. Is the request payload shape what the server expects? (compare DTO with frontend fetch)
-
-If ANY is plausible and not verified → investigate before marking done.
-
----
-
-#### BACKEND: API Integration Test Generation
-
-**Activates when**: Changed files match `*.controller.*`, `*.service.*`, `*.resolver.*`, `/routes/`, `/api/`, `*.dto.*`, `*.guard.*`, `*.middleware.*`
-
-Run detection: `node node_modules/wogiflow/scripts/flow-runtime-verification.js api-detect [changed-files...]`
-
-**For EACH acceptance criterion that involves an API endpoint**:
-
-1. **Identify the endpoint**: method (GET/POST/PUT/PATCH/DELETE), path, expected request/response shape
-2. **Generate an integration test** that:
-   - Makes the actual HTTP request to the running dev server
-   - Asserts the status code matches expected
-   - Asserts the response body contains expected fields
-   - For mutations (POST/PUT/PATCH/DELETE): re-fetches the resource to verify persistence
-   - For auth-protected endpoints: includes the auth token
-3. **Write the test** to `tests/verification/api-verify-{taskId}.test.js`
-4. **Run the test**: `node --test tests/verification/api-verify-{taskId}.test.js`
-5. **If test fails** → debug, fix the implementation, re-run (max 5 retries)
-6. **Test persists** as a regression guard
-
-**API Test Template** (generated per criterion):
-
-```javascript
-it('POST /api/pipeline-rules — creates a rule with correct fields', async () => {
-  const res = await apiRequest('POST', '/api/pipeline-rules', {
-    tagPattern: 'animation',
-    routeTo: { type: 'department', id: 'dept-123' },
-    mode: 'CLAIMABLE'
-  });
-
-  // Status check
-  assert.equal(res.status, 201);
-
-  // Response shape check
-  assert.ok(res.data.id, 'Response missing field: id');
-  assert.equal(res.data.tagPattern, 'animation');
-  assert.equal(res.data.mode, 'CLAIMABLE');
-
-  // Persistence check: re-fetch and verify stored
-  const verify = await apiRequest('GET', `/api/pipeline-rules/${res.data.id}`);
-  assert.equal(verify.status, 200);
-  assert.equal(verify.data.tagPattern, 'animation');
-});
-```
-
-**Boundary verification** (frontend↔backend):
-When the task is `fullstack` (both UI and API files changed):
-1. Generate BOTH browser tests AND API tests
-2. The API test verifies the server accepts the payload shape the frontend sends
-3. The browser test verifies the UI correctly displays the response shape the server returns
-4. If either fails → the boundary contract is broken
-
-**Quick verification via curl** (for manual checking):
-The AI can also generate and run curl commands directly:
-```bash
-# Create a rule
-curl -s -X POST http://localhost:3000/api/pipeline-rules \
-  -H "Content-Type: application/json" \
-  -d '{"tagPattern":"animation","routeTo":{"type":"department","id":"dept-123"},"mode":"CLAIMABLE"}'
-
-# Verify it was stored
-curl -s http://localhost:3000/api/pipeline-rules | jq '.[-1]'
-```
-
----
-
-#### Configuration
-
-```json
-{
-  "runtimeVerification": {
-    "enabled": true,
-    "autoGenerateTests": true,
-    "frontend": {
-      "method": "webmcp",
-      "fallback": ["playwright", "checklist"],
-      "devServerUrl": "http://localhost:5173"
-    },
-    "backend": {
-      "method": "api-test",
-      "fallback": ["curl", "checklist"],
-      "baseUrl": "http://localhost:3000"
-    },
-    "testOutput": "tests/verification",
-    "persistTests": true,
-    "blockOnFailure": true
-  }
-}
-```
-
-**`autoGenerateTests: true`** (default) — Tests are generated for EVERY task. This is the core behavioral change: verification is not an afterthought, it's built into the execution loop.
-
-**`persistTests: true`** (default) — Generated tests stay in `tests/verification/` as permanent regression guards. Over time, this builds an automated test suite from the actual use cases that were implemented.
-
-**`blockOnFailure: true`** (default) — If generated tests fail, the task is NOT complete. The agent must fix the implementation until tests pass.
-
-#### Skip Conditions
-
-- `config.runtimeVerification.enabled: false` → skip entirely (not recommended)
-- Task has NO code files in changed set (docs-only, config-only) → skip
-- Task is L3 trivial AND no UI/API files → skip
-
-### Step 3.6: Integration Wiring Validation (MANDATORY)
-
-Run `node node_modules/wogiflow/scripts/flow-wiring-verifier.js wf-XXXXXXXX`
-
-**Forward wiring** — For each created file, verify it's imported/used somewhere:
-- Entry points (index.ts, App.tsx, *.config.ts, tests) don't need imports
-- Components MUST be imported in a parent. Hooks MUST be called. Utilities MUST be imported.
-- If NOT wired: identify where to import, wire it up, re-verify.
-
-**Removal impact** (v1.9.3) — For each removed export, type member, or identifier, verify no consumers still reference it:
-- Runs automatically as part of the `integrationWiring` quality gate
-- Detects orphaned references: removed type union members, exported names, component references, string literal IDs (e.g., tab IDs, route keys)
-- If orphaned references found: update consumers to remove stale references, re-verify.
-- CLI: `node node_modules/wogiflow/scripts/flow-wiring-verifier.js removal-check [files...]`
-
-### Step 3.7: Standards Compliance Check (MANDATORY)
-
-Run `node node_modules/wogiflow/scripts/flow-standards-gate.js wf-XXXXXXXX [changed-files...]`
-
-Checks scoped by task type: component → naming/components/security. Utility → naming/functions/security. API → naming/api/security. Bugfix → naming/security. Feature → all. Refactor/migration → all + consumer-impact verification.
-
-**Consumer impact check** (ALL L1+ tasks): For each BREAKING consumer from explore phase (blast-radius analysis), verify it was updated. If any NOT migrated → BLOCK task completion. Results are persisted in `.workflow/state/blast-radius-{taskId}.json`.
-
-**Reuse candidate check** (AI-as-Judge): Standards gate returns similar items from all registries. AI reasons about PURPOSE overlap (not just name). If purpose overlaps → ask user (use existing / extend / create new). If purpose clearly differs → proceed silently.
-
-If violations found: fix, re-run, only proceed when all pass. Violations auto-recorded to `feedback-patterns.md`; 3+ occurrences → promoted to `decisions.md` (project-level) or fixed in WogiFlow base code (product-level). See `/wogi-decide` Step 0.5 for product vs project classification.
-
-### Step 4: Quality Gates + Final Verification
-
-**First**: Run `node node_modules/wogiflow/scripts/flow-spec-verifier.js verify wf-XXXXXXXX` — verify all spec deliverables exist. If missing → STOP, create them.
-
-**Then**: Check `config.qualityGates` for task type. Gates are type-specific:
-- **feature**: loopComplete, tests, registryUpdate, requestLogEntry, integrationWiring, standardsCompliance
-- **bugfix**: loopComplete, tests, requestLogEntry, standardsCompliance, learningEnforcement
-- **refactor**: loopComplete, tests, noNewFeatures, smokeTest, standardsCompliance
-- **chore**: requestLogEntry, outstandingFindings
-- **release**: requestLogEntry, outstandingFindings, preRelease
-- **fix**: loopComplete, requestLogEntry, standardsCompliance
-
-**Fallback behavior**: Task types not listed above (docs, style, test, perf, etc.) inherit the **feature** gates. This is intentional — feature gates are the most comprehensive and serve as a safe default.
-
-**Key automated gates** (v1.9.7):
-- `registryUpdate` → runs `flow registry-manager scan` on ALL active registries (app-map, function-map, api-map, schema-map, service-map). Auto-updates maps when new entries found. Replaces old `appMapUpdate` no-op gate.
-- `integrationWiring` → calls `verifyWiring()` — checks created files are imported/used
-- `standardsCompliance` → calls `runTaskStandardsCheck()` — checks naming, security, decisions.md rules
-- `outstandingFindings` → reads `last-review.json` — blocks if unresolved critical/high findings exist
-- `preRelease` → verifies codebase is releasable (no outstanding findings + lint + typecheck)
-
-**CRITICAL**: No task type defaults to zero gates. Every task type MUST have at least `requestLogEntry` + `outstandingFindings`.
-
-**WebMCP** (optional): If `config.webmcp.enabled` and UI files changed, check tool coverage. Non-blocking.
-
-Reflection: "Have I introduced any bugs or regressions?"
-
-### Step 5: Finalize
-
-1. Reflection: "Does this match what the user asked for?"
-2. Close out all TodoWrite items for this task
-3. Move task to recentlyCompleted in ready.json
-4. Registry maps auto-updated by `registryUpdate` quality gate (runs `flow registry-manager scan` on all active registries — app-map, function-map, api-map, schema-map, service-map)
-5. If `config.webmcp.enabled` and UI files created: run `node node_modules/wogiflow/scripts/flow-webmcp-generator.js scan`
-6. Commit: `feat: Complete wf-XXXXXXXX - [title]`
-7. Show completion summary
-
-## Options
-
-| Flag | Effect |
-|------|--------|
-| `--tdd` | Test-first mode (see `.claude/docs/tdd-mode.md`) |
-| `--no-loop` | Load context only, don't execute |
-| `--no-spec` | Skip spec generation |
-| `--no-skills` | Skip skill auto-loading |
-| `--no-reflection` | Skip reflection checkpoints |
-| `--max-retries N` | Limit retries per scenario (default: 5) |
-| `--pause-between` | Confirm between scenarios |
-| `--verify-only` | Run verification only |
-| `--phased` | Phased execution: Contract → Skeleton → Core → Edge Cases → Polish |
-
-## When Things Go Wrong
-
-**Scenario keeps failing** (max retries): Stop, report, leave in inProgress. For HIGH-RISK tasks (architecture/migration/refactor, complexity HIGH + files > 10), suggest Best-of-N via `flow-best-of-n.js`. For others, suggest `/wogi-debug-hypothesis`.
-
-**Best-of-N** (when `config.bestOfN.enabled`): `assessRisk()` checks if task qualifies. If yes, offer to spawn N agents in worktrees with Opus judging the winner.
-
-**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, do NOT show a summary, do NOT invoke `/wogi-pre-compact`. Just compact silently and continue with the next task. The PostCompact hook restores all state automatically. Mid-task: commit progress, compact silently, resume from checkpoint. The user should never see compaction happen — it's invisible infrastructure.
-
-## 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
-```
+Defaults: engineering/naming → agent-decides. infrastructure/performance → agent-decides-report-after. productBehavior/ux → owner-decides. security → auto-fix-report-after. Max 5 owner questions per batch (overflow → agent-decides-report-after). User can update via `/wogi-decide`. Low-confidence classification defaults to `owner-decides` (safest fallback).
 
-### Phase Mapping for /wogi-start Execution
+## Phase Execution (MANDATORY)
 
-| 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 |
+Before executing ANY phase, you MUST Read the phase instruction file. The PreToolUse hook BLOCKS Edit/Write/Bash until the phase file is read.
 
-### Skip Conditions
+| Phase | File to Read | Contents |
+|-------|-------------|----------|
+| exploring | `.claude/docs/phases/01-explore.md` | Steps 1–1.45: Context loading, intent framing, clarifying questions, item reconciliation, multi-agent research, reuse gate, scope-confidence audit |
+| spec_review | `.claude/docs/phases/02-spec.md` | Steps 1.55–2.5: Architect pass, logic adversary, spec generation, approval gate, test generation, TodoWrite decomposition, TDD check |
+| coding | `.claude/docs/phases/03-implement.md` | Steps 3–3.52: Scenario execution loop, sprint resets, criteria completion verification, sub-agent output verification |
+| validating | `.claude/docs/phases/04-verify.md` | Steps 3.55–3.9: Inventory verification, skeptical evaluator, runtime verification (frontend + backend), wiring validation, standards compliance, completion truth gate |
+| completing | `.claude/docs/phases/05-complete.md` | Steps 4–5: Quality gates, finalization, progress tracking, mandatory rules, options, error handling |
 
-- **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)
+**How it works**: When you transition to a new phase, Read the corresponding file BEFORE using Edit/Write/Bash. The phase-read gate tracks which files you've read and blocks mutation tools until the current phase's file is loaded.
 
 ## Mandatory Rules