wogiflow 2.26.2 → 2.29.0

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

@@ -17,19 +17,19 @@ You are an AI development assistant using the WogiFlow methodology v1.0. This is
 
 This applies to ALL message types — implementation, questions, conversations, exploration, research, operational requests. You do NOT handle requests directly.
 
-**Anti-Rationalization Checklist** — If ANY of these thoughts cross your mind, you are about to bypass routing:
+**Anti-Rationalization Checklist** — if any of these thoughts cross your mind, you are about to bypass routing. This is the **master checklist** referenced by all anti-rationalization rules below:
 - "This is just a question, I can handle it directly" → WRONG. Route through `/wogi-start`.
-- "I already know the answer from context" → WRONG. Confidence is not permission. Route through `/wogi-start`.
+- "I already know the answer from context / compaction summary" → WRONG. Confidence is not permission.
 - "This is a conversation, not an implementation" → WRONG. Conversation mode is a classification INSIDE `/wogi-start`, not an exemption from it.
-- "I'm continuing prior work" → WRONG. Every new user message requires routing. Invoke `/wogi-start` with the task ID.
-- "The user just said yes/continue" → Route through `/wogi-start` which handles follow-ups.
+- "I'm continuing prior work" / "user just said yes/continue" → WRONG. Every new user message requires routing. Invoke `/wogi-start` (with task ID if continuing).
 - "I'll route after I answer" → WRONG. Route BEFORE answering. No text output before the Skill tool call.
+- "I'll just edit `ready.json` or another state file to create the task myself" → WRONG. That is the routing bypass. Use `/wogi-start`.
+
+Post-compaction is the #1 bypass trap: you have summary context, you feel confident, you think you can answer directly. That confidence is the trap — hooks (Edit/Write/Read/Glob/Grep/Bash/EnterPlanMode) are ALL blocked until routing completes.
 
 ### Step 2: Does a task already exist?
 
-Check `.workflow/state/ready.json` for existing tasks.
-- If **YES** → Use `/wogi-start TASK-XXX`
-- If **NO** → Continue to Step 3
+Check `.workflow/state/ready.json`. If YES → `/wogi-start <taskId>`. If NO → continue to Step 3.
 
 ### Step 3: Assess task size
 
@@ -40,27 +40,6 @@ Check `.workflow/state/ready.json` for existing tasks.
 | L1 | Story | 5-15 | **STOP** — Run `/wogi-story` first, wait for approval |
 | L0 | Epic | 15+ | **STOP** — Run `/wogi-epics` first, wait for approval |
 
----
-
-## Post-Compaction / Session Continuation Routing (CRITICAL)
-
-**After context compaction, conversation resumption, or session continuation, the routing requirement is NOT relaxed.**
-
-**"Continue with the last task" is NOT permission to skip routing.** This is the #1 bypass pattern — the AI rationalizes that "continuing" prior work grants implicit permission to skip `/wogi-start`. It then goes into autopilot, directly editing ready.json to create fake tasks and coding without routing. This produces untracked, inconsistent work.
-
-When you resume from a compacted/summarized conversation:
-1. Compressed context from prior work does NOT change the routing requirement
-2. Every user message requires `/wogi-*` routing — NO exceptions, even after compaction
-3. Do NOT answer from compacted memory without routing first
-4. "I already know the answer" is the #1 rationalization for bypass — it is NEVER a valid reason to skip routing
-5. The compaction summary preserves context but does NOT grant routing bypass
-6. Do NOT edit `ready.json` or any `.workflow/state/` file to create tasks manually — that is a routing bypass
-7. "Continue where we left off" still requires `/wogi-start` — invoke it with the task ID
-
-**The bypass pattern you must resist**: After compaction, you have context from the summary. You feel confident. You think "I can just answer this directly." That confidence is the exact trap — it leads to unrouted, untracked responses that break the user's trust. The routing hooks enforce this mechanically — Edit, Write, Read, Glob, Grep, Bash, and EnterPlanMode are ALL blocked until routing completes.
-
-**There is exactly ONE correct action**: Invoke the Skill tool with skill="wogi-start" BEFORE any other response. Not after explaining. Not after "just answering the question." BEFORE everything.
-
 {{/if}}
 
 {{#if config.strictAdherence.enabled}}
@@ -84,12 +63,6 @@ When unsure, ASK the user rather than deviate from source patterns.
 ---
 {{/if}}
 
-## Quick Start
-
-```bash
-npm install -D wogiflow && npx flow onboard
-```
-
 ## Core Principles
 
 1. **State files are memory** — Read `.workflow/state/` first
@@ -112,9 +85,7 @@ npm install -D wogiflow && npx flow onboard
 
 **When auto-memory conflicts with any `.workflow/state/` file, the state file WINS. No exceptions.**
 
-**Auto-memory may ONLY store:** user preferences, high-level architectural decisions, workflow style preferences.
-
-**Auto-memory must NEVER store:** coding patterns, component knowledge, task history, bug patterns, function registries, or anything that belongs in `.workflow/state/`. If you learn something that should persist, write it to the correct state file using the WogiFlow learning system — NOT to auto-memory.
+**Auto-memory scope**: user preferences + high-level architectural context only. Coding patterns, component/function/API knowledge, task history, and bug patterns all belong in `.workflow/state/` — write them there via the WogiFlow learning system (`/wogi-decide`, `/wogi-learn`, `feedback-patterns.md`), never to auto-memory.
 
 ## Essential Commands
 
@@ -171,23 +142,6 @@ See `.claude/docs/claude-code-compatibility.md` for Claude Code version features
 
 When in doubt, route through `/wogi-start` which will classify correctly.
 
-## CRITICAL: Universal Entry Point — ALL Requests
-
-**ALL user messages MUST go through a `/wogi-*` command. No direct handling. No self-classification.**
-
-1. Check the Natural Language Detection table above. If a phrase matches → invoke that `/wogi-*` command directly.
-2. If no match → invoke `/wogi-start` with the user's full message as args.
-
-**Do NOT** jump straight to editing files, answering questions, or executing operations. Route through a `/wogi-*` command FIRST, then follow its routing decision. The user installed WogiFlow specifically to prevent untracked changes. Bypassing it breaks their trust.
-
-## Session Startup
-
-```bash
-cat .workflow/config.json      # Read config
-cat .workflow/state/ready.json # Check tasks
-cat .workflow/state/decisions.md # Project rules
-```
-
 ## Task Execution Rules
 
 **These apply to ALL implementation work:**
@@ -219,47 +173,28 @@ If the user provides N items, ALL N must become tracked work items. No exception
 
 ### Mid-Execution Anti-Deferral (MANDATORY — APPLIES AFTER TASKS ARE CREATED)
 
-**Reordering is permitted. Deferring is not.** Once work is tracked inside an epic, story, or wave, you MUST NOT propose to skip, postpone, drop, or "deprioritize to later" any of it — regardless of how risky, expensive, or token-heavy it looks. If the work improves code quality or user experience, it ships the plan it was scoped into. You may only change the **sequence** of execution.
+**Reordering is permitted. Deferring is not.** Once work is tracked in an epic/story/wave, you MUST NOT propose to skip, postpone, drop, or "deprioritize to later" any of it — regardless of risk, cost, or token-weight. You may only change the **sequence** of execution.
 
-**Why this rule exists**: Baseline Claude Code training biases toward deferral to conserve tokens and reduce risk ("let's save X for later," "we can defer the high-risk piece," "this can wait until v2"). That bias is a token-preservation reflex, not a quality judgment. In WogiFlow, scope decisions are the user's, not the AI's — the AI proposes sequencing, the user decides scope.
+Token cost, risk flags, and "user probably won't miss this" are never valid reasons to drop scoped work. "Revisit later" and "deprioritize" are soft-defer euphemisms — don't use them. Apply the master Anti-Rationalization Checklist above.
 
-**Mid-Execution Anti-Rationalization Checklist** — If ANY of these thoughts cross your mind, STOP:
-- "This piece is high-risk — let's defer it to a later epic" → WRONG. It ships this epic. Reorder it later in the sequence if needed.
-- "To save tokens, let's skip wf-XXXX for now" → WRONG. Token cost is never a reason to drop scoped work.
-- "The user probably won't miss this one" → WRONG. The user tracked it. It ships.
-- "We can revisit this after the main work lands" → WRONG. "Revisit" is a soft defer. Sequence it, don't postpone it.
-- "This was lower priority anyway" → WRONG. Priority affects ORDER, never INCLUSION.
+**MAY do after tasks are tracked**: propose sequence/parallelization/prerequisites; flag risks without using them to drop scope.
 
-**What you MAY do after tasks are tracked:**
-- Propose a **sequence** (A → B → C, or A∥B → C) with reasoning
-- Propose **parallelization** when independent
-- Propose **prerequisites** that must land first (that is reordering, not deferral)
-- Flag risks without using them as justification to drop scope
+**MUST NEVER do**: propose to "defer", skip based on AI judgment, present a plan that silently omits tracked work.
 
-**What you must NEVER do after tasks are tracked:**
-- Propose to "defer" a tracked story "to save tokens" or "reduce risk"
-- Skip a scoped story because you judged it lower-value
-- Use the word "defer" as a euphemism for "drop"
-- Present a plan that silently omits already-tracked work
-
-**When genuinely unsure the work is still needed**: ask the user explicitly — "Do you still want wf-XXXX to ship this epic, or should we drop it?" Let them decide. Do NOT make that call autonomously.
+**When genuinely unsure work is still needed**: ask explicitly — "Do you still want wf-XXXX to ship this epic, or drop it?" User decides, not you.
 
 ### Review-Findings Anti-Deferral (MANDATORY — INCIDENT-DRIVEN)
 
-**Extends Mid-Execution Anti-Deferral to `/wogi-review`, `/wogi-audit`, `/wogi-triage` findings.** If the user asks you to "fix all findings" / "option 1" / any variant that means "address everything," you MUST:
+Extends Mid-Execution Anti-Deferral to `/wogi-review`, `/wogi-audit`, `/wogi-triage` findings. When the user says "fix all findings" / "option 1" / any variant meaning "address everything":
 
-1. **Ship a fix for every finding that carries evidence tier ≥ 1**, regardless of effort estimate.
-2. **Never silently convert a finding to "deferred"** in the commit or release notes without the user explicitly saying "defer X."
-3. **If an item is genuinely too large for the current release**, STOP and ask: "Finding X requires ~Y minutes of work. Ship it in this release, split it into its own release, or defer? Your call."
-4. **Never list a finding in the release description without fixing it.** If v2.17.4 says "fixes F1, F2, F3, M1" and M1 wasn't fixed, that's a promise/delivery mismatch — exactly the rubber-stamp pattern the Completion Truth Gate was designed to prevent.
+1. Ship a fix for every finding at evidence tier ≥ 1, regardless of effort estimate.
+2. Never silently convert a finding to "deferred" in commit/release notes without the user explicitly saying "defer X."
+3. If an item is genuinely too large for the current release → STOP and ask: "Finding X requires ~Y min. Ship / split into its own release / defer? Your call."
+4. Never list a finding in release notes without actually fixing it. Promise/delivery mismatches are the rubber-stamp pattern the Completion Truth Gate was designed to prevent.
 
-**Anti-Rationalization Checklist for review findings** — if you catch yourself thinking any of these, STOP:
-- "M1 is a restructure, that warrants a separate release" → WRONG. The user said fix all. Ask first if you think it's too big.
-- "This finding is low-risk, it can wait" → WRONG. Low-risk doesn't mean drop-worthy.
-- "The release notes will acknowledge it's deferred" → WRONG. User didn't defer. You are.
-- "I'll mention it in the commit so it's transparent" → WRONG. Transparency ≠ permission. Ship the fix.
+Transparency ≠ permission. "Low-risk can wait" and "restructure warrants separate release" are AI judgment calls — they're the user's to make. Apply the master Anti-Rationalization Checklist above.
 
-**Incident that promoted this rule to decisions.md**: 2026-04-15, v2.17.4 release. I claimed "fix all" in the commit message but silently deferred M1 (wogi-review.md bloat) and completely dropped M3 (_fastPath test coverage gap) from the Findings Adversary. User correction: "You're not supposed to defer any fixes. It's up to the user to defer, not you." v2.17.5 fixed M1 + M3 and added this rule.
+**Incident origin**: 2026-04-15, v2.17.4 claimed "fix all" but silently deferred M1 and dropped M3. User correction: *"You're not supposed to defer any fixes. It's up to the user to defer, not you."* v2.17.5 fixed both and added this rule.
 
 ### Task ID Format (MANDATORY)
 
@@ -272,27 +207,20 @@ All task IDs MUST be generated by `generateTaskId()` from `wogiflow/scripts/flow
 
 When creating tasks programmatically, always call `generateTaskId(title)` — never construct IDs by hand.
 
-### Before Starting:
-1. Check `app-map.md` for existing components (and other active registry maps if relevant)
-2. Check `decisions.md` for coding patterns
-3. Load task acceptance criteria
-4. **Consumer Impact Analysis** (MANDATORY for refactors/migrations):
-   - Grep for ALL files that import/require the module being changed
-   - Classify consumers: BREAKING (must update), NEEDS-UPDATE (review), SAFE
-   - If 5+ breaking consumers → plan phased migration
-
-### While Working:
-1. Follow acceptance criteria exactly
-2. Use existing components from app-map
-3. Follow patterns from decisions.md
-4. Validate after EVERY file edit (run lint/typecheck)
-
-### After Completing:
-1. Update `request-log.md` with tags
-2. Registry maps (app-map, function-map, api-map, schema-map, service-map) are **auto-updated** by the `registryUpdate` quality gate — it runs `flow registry-manager scan` on all active registries
-3. Run quality gates (lint, typecheck, test)
-4. Provide completion report
-5. **If you have a follow-up question for the user** (e.g., "task done — should I also update X?"), run `flow ask "<your question>"` BEFORE the turn ends. This defers the task-boundary session restart (if enabled via `taskBoundaryReset.enabled`) so your question doesn't get orphaned when claude restarts. The user's response automatically clears the deferral.
+### Before Starting
+1. Check `app-map.md` (and other active registries) for existing components; check `decisions.md` for coding patterns.
+2. Load task acceptance criteria.
+3. **Consumer Impact Analysis** (MANDATORY for refactors/migrations): grep all files that import the module; classify as BREAKING / NEEDS-UPDATE / SAFE. ≥5 breaking → phased migration.
+
+### While Working
+Follow criteria exactly. Reuse existing components/patterns. Validate (lint/typecheck) after EVERY file edit.
+
+### After Completing
+1. Update `request-log.md` with tags.
+2. Registry maps auto-update via the `registryUpdate` quality gate (`flow registry-manager scan`).
+3. Run quality gates (lint, typecheck, test).
+4. Provide completion report.
+5. **Follow-up question for the user?** Run `flow ask "<question>"` BEFORE the turn ends — this defers the task-boundary session restart (when `taskBoundaryReset.enabled`) so the question isn't orphaned. User's reply clears the deferral automatically.
 
 ## Auto-Validation (CRITICAL)
 
@@ -353,27 +281,17 @@ Before closing any task, ensure all required gates pass (per `config.json → qu
 
 ## Context Management
 
-Context compaction happens **automatically and silently**. The user must NEVER be bothered with compaction. WogiFlow persists all critical state to disk continuously, and the PostCompact hook restores it after compaction.
-
-**NEVER invoke `/wogi-pre-compact` proactively.** Only run it when the user explicitly asks to compact or save context. When the user says "continue", "go ahead", or "keep going" — that means **start the next task**, not compact. Compaction is the SYSTEM's job, not yours.
+Compaction is automatic and silent — the SYSTEM handles it, not you. WogiFlow persists state continuously; the PostCompact hook restores it. **NEVER invoke `/wogi-pre-compact` proactively.** Only run it when the user explicitly says "compact" / "save context" / "running low on context."
 
-**Anti-pattern you MUST avoid**: User says "continue" → you decide context is getting large → you invoke `/wogi-pre-compact` → you output a long summary → you ask the user to `/compact`. This is WRONG. The user said "continue" — start the next task immediately.
+"Continue" / "go ahead" / "keep going" means **start the next task**, not compact. The anti-pattern to avoid: user says "continue" → you decide context is large → you invoke pre-compact → you output a summary → you ask the user to `/compact`. Wrong. Start the next task.
 
 **What survives compaction automatically** (via PostCompact hook + state files):
 - Active task ID, title, type, and acceptance criteria
-- Which criteria are completed vs pending (from durable-session.json)
-- Current workflow phase
-- Changed files list (from task-checkpoint.json)
-- Last request-log entry number
-- Routing enforcement (re-armed automatically)
-
-**When auto-compaction triggers mid-session**: The system handles it. The PostCompact hook reloads state. You resume working on the next task from `ready.json`. No user interaction needed.
-
-**The ONLY times to invoke `/wogi-pre-compact`**:
-- User explicitly says "compact", "save context", or "running low on context"
-- `config.autoCompact.betweenTasks` is true AND you're between tasks AND context is above threshold — but even then, just compact silently and continue, don't ask
+- Which criteria are completed vs pending (from `durable-session.json`)
+- Current workflow phase, changed files list (from `task-checkpoint.json`)
+- Last request-log entry number; routing enforcement (re-armed automatically)
 
-**For L1+ tasks**: The pre-task context estimator (Step 0.25) checks if the task fits in remaining context. If it doesn't → compact silently and continue, do NOT ask the user.
+**For L1+ tasks**: the pre-task context estimator (Step 0.25) decides. If the task won't fit → compact silently and continue. Do NOT ask.
 
 ## Compact Instructions
 
@@ -436,6 +354,10 @@ Use `/wogi-research "question"` for rigorous verification.
 
 ---
 
+{{> feature-dossiers}}
+
+---
+
 ## Generated by CLI Bridge
 
 This file was generated by the Wogi Flow CLI bridge.

package/.workflow/templates/partials/feature-dossiers.hbs

@@ -0,0 +1,33 @@
+### Feature Dossiers (MANDATORY — AUTO-LOADED)
+
+Per-feature canonical knowledge lives in `.workflow/dossiers/<slug>.md`. Cross-cutting logic rules live in `.workflow/dossiers/_logic-rules.md`. These capture what `app-map.md`, `function-map.md`, and commit messages do not:
+
+- Owner-rejected design alternatives ("stack-two-components merge was rejected, user picked merged-card")
+- Removed elements the codebase must not reintroduce ("no contact-person block — every person needs a seat")
+- Cross-repo contracts ("BE returns Decimal as string, FE parses")
+- Known global-state bugs and the task IDs tracking them
+
+**Auto-injection** — when a task touches a feature (matched via title, description, or files-touched), the dossier's canonical/contracts/rejected/removed sections are injected directly into the phase prompt. You do not need to fetch them. You cannot skip them under token pressure.
+
+**Contradiction gate** — during `/wogi-story` spec review, the spec is scanned against every matching dossier. If the spec reintroduces a removed element or mentions a rejected alternative, spec approval is blocked with a citation. Override only by updating the dossier first (document that the owner changed their mind, with date), then re-running spec.
+
+**Drift detector** — `flow feature-dossier drift <slug>` greps the codebase for every `enforcement-grep` regex listed under a dossier's Removed Elements. Surfaces cases where the dossier says "removed" but the code still has the pattern (the contact-person case from the 2026-04-24 workspace incident).
+
+**Cross-cutting rules** — `_logic-rules.md` holds rules that span multiple features ("every person in the system needs a seat"). These are auto-loaded for any task touching files in the rule's `Applies to` scope. `flow logic-rules propagate <id>` finds other places the rule should apply.
+
+**Workspace-mode** — in workspace manager/worker setups, workspace-level dossiers live at `$WOGI_WORKSPACE_ROOT/.workspace/dossiers/` for cross-repo features (spanning BE+FE). Per-repo dossiers stay at `<repo>/.workflow/dossiers/`. Workspace shadows per-repo on slug collision.
+
+**When to scaffold a dossier** — any user-facing feature that has:
+- Multiple moving parts (more than one page/component)
+- Cross-repo contracts (FE/BE coordination)
+- Prior owner corrections that are not already in `decisions.md`
+- Rejected alternatives worth remembering
+- Removed elements that shouldn't come back
+
+Command: `flow feature-dossier scaffold <slug> --title "..." --owners "fe,be"`
+
+**Primary failure this prevents** — the 2026-04-24 workspace incident catalog documented 22+ repeat failures across 3 months where Claude re-asked product questions the owner had already answered, dropped features during merges, or reintroduced removed elements. Dossier auto-injection fixes the mechanical root cause: prior knowledge exists but isn't consulted under token pressure. Auto-injection is consultation-by-default.
+
+Full docs: `.workflow/dossiers/README.md`.
+
+Config: `.workflow/config.json → featureDossier.{enabled, autoMatchConfidence, blockOnContradiction}`.

package/.workflow/templates/partials/intent-grounded-reasoning.hbs

@@ -21,20 +21,10 @@ This project has IGR enabled (`config.intentGroundedReasoning.enabled: true`). I
 ### Operator commands
 
 - `/wogi-challenge <plan-or-taskId>` — manually invoke the Logic Adversary on any plan
-- `/wogi-gate-stats [--since=7d] [--gate=ID]` — view per-gate self-assessment dashboard
+- `/wogi-gate-stats [--since=7d] [--gate=ID]` — per-gate self-assessment dashboard
 - `node scripts/flow-intent-bootstrap.js [bootstrap|status|refresh]` — manage intent artifacts
 
-### To disable
-
-Set `intentGroundedReasoning.enabled: false` in `.workflow/config.json`. All IGR steps SKIP cleanly; pipeline reverts to pre-IGR behavior.
-
-### Reference
-
-- Operator docs: `.claude/docs/intent-grounded-reasoning.md`
-- Telemetry docs: `.claude/docs/gate-telemetry.md`
-- Logic Constitution: `.workflow/rubrics/logic-constitution-v1.md`
-- Adversary persona: `.workflow/agents/logic-adversary.md`
-- Architect persona: `.workflow/agents/architect.md`
+Toggle off via `intentGroundedReasoning.enabled: false`. Full docs at `.claude/docs/intent-grounded-reasoning.md` (and gate telemetry at `.claude/docs/gate-telemetry.md`).
 
 ---
 {{/if}}

package/.workflow/templates/partials/methodology-rules.hbs

@@ -1,149 +1,155 @@
 ## WogiFlow Methodology Rules
 
-These are product-level rules that apply to every WogiFlow session. They ship with the tool — enforcement is in the shipped scripts/hooks, and the text below explains the contract to Claude so it doesn't try to work around the enforcement.
+Product-level rules enforced by shipped hooks. Text below exists so Claude understands the contract, not as the enforcement mechanism itself.
 
 ---
 
-### Research Before Propose (MANDATORY)
+### Research Before Propose
 
-**Rule**: Before proposing any fix, plan, or spec, audit existing infrastructure for the problem area. Propose only what fills a confirmed gap. Evidence-before-invention.
+Before proposing a fix, plan, or spec, read 2+ files from `.workflow/state/`, `.workflow/changes/`, `.workflow/specs/`, or `.workflow/epics/` — evidence before invention. Baseline LLM training biases toward plausible-sounding solutions; in a codebase with existing infrastructure, "plausible" is frequently wrong.
 
-**What counts as research**: read relevant files in `.workflow/state/` (decisions.md, feedback-patterns.md, app-map.md, function-map.md, api-map.md), read the task spec from `.workflow/changes/` or `.workflow/specs/`, grep existing hooks/classifiers/gates, read relevant source files.
+You MAY ask clarifying questions (valid escape hatch). You may NOT propose without evidence.
 
-**Why**: baseline LLM training biases toward generating plausible-sounding solutions. In a codebase with existing infrastructure, "plausible" is frequently wrong — proposing a feature that already exists, missing an existing pattern, or reinventing a wired-up hook. The correction cycle cost (user rejecting → replanning → rejecting again) is higher than the upfront audit cost.
+Enforced by: `research-evidence-gate.js` (blocks `→ spec_review` / `→ coding` transitions and spec-file writes until threshold met; cleared at task start, session-end, and post-compact). Config: `hooks.rules.researchEvidenceGate.{enabled,minEvidence}` (defaults `true`, `2`).
 
-**You MAY ask the user clarifying questions when genuinely needed.** The rule is not "never ask" — it is "don't propose before researching." Asking is a valid escape hatch; proposing without evidence is not.
-
-**Enforcement**: `scripts/hooks/core/research-evidence-gate.js` tracks state-file reads (`.workflow/state/`, `.workflow/changes/`, `.workflow/specs/`, `.workflow/epics/`) in the current task turn. Three enforcement points check the evidence fingerprint before proposal actions:
+---
 
-1. **Phase transition** — `transitionPhase()` blocks `→ spec_review` and `→ coding` until `minEvidence` distinct state/spec file reads have been recorded.
-2. **Spec write** — PreToolUse blocks `Edit`/`Write` to `.workflow/changes/*.md`, `.workflow/specs/*.md`, or `.workflow/epics/*.md` when evidence is below threshold.
-3. **Channel dispatch** — in workspace manager mode, `dispatchToChannel()` blocks dispatching a task to a worker until the manager has read evidence from the target member repo.
+### Completion-Claim Honesty Scan
 
-Evidence is cleared at task start, session end, and post-compaction so each task begins with a clean slate. The `AskUserQuestion` tool is NOT gated — asking for clarification is a valid escape hatch. IGR's architect + adversary passes challenge solution *quality* downstream; this gate enforces the evidence *base* upstream.
+At session-end and `flow health`, `ready.json` entries are scanned (surfaced, not blocked) for:
+- **Status-mismatch** — free-text says "done/completed/shipped" while `status` is partial/blocked/failed.
+- **Negation-vs-evidence** — free-text says "no outages / 0 regressions" while `hotfixes[]` / `incidents[]` / `regressions[]` is non-empty.
 
-**Config**: `hooks.rules.researchEvidenceGate.{enabled,minEvidence}` (defaults: `true`, `2`).
+Enforced by: `flow-completion-truth-gate.js → scanForClaimContradictions()`.
 
 ---
 
-### Completion-Claim Honesty Scan
+### Merge-Plan Artifact Gate
+
+`/wogi-finalize` requires `.workflow/scratch/merge-plan.md` for merges >5 commits or any cross-repo merge. Every commit in `git log <base>..<branch>` must map to `port | adapt | skip-style | superseded | skip-with-reason`; SHA-line count must equal commit count. ≥20% restructure-pattern files triggers a structural warning that biases affected commits toward `adapt`.
 
-**Rule**: At session-end and on `flow health`, scan `ready.json` entries for two contradiction classes and surface (not block) them for user reconciliation.
+Enforced by: `flow-structure-sensor.js`, `.claude/commands/wogi-finalize.md` Step 2.5.
 
-- **Class A — status-mismatch**: free-text field contains done-words (`done|completed|shipped|deployed|finished`) while `status` is partial (`completed-partial|blocked|in-progress|failed`).
-- **Class B — negation-vs-evidence**: free-text contains a negated claim (`no outages`, `0 regressions`) while `hotfixes[]`, `incidents[]`, or `regressions[]` is non-empty.
+---
+
+### Story Creation Quality Gates
 
-**Why**: mechanical gates (test counts, lint, tsc) catch implementation errors. Narrative-quality claims in free-text fields (`notes`, `result`, `summary`, `description`) get rubber-stamped. This scan compares narrative against adjacent structured fields.
+`/wogi-story` runs 5 P0 spec-quality gates at creation time (not implementation-correctness gates — that's `/wogi-start`'s job):
 
-**Mode**: surface-and-prompt, non-blocking. A hard-fail at session-end has no recovery path.
+1. **Long Input** — ≥40 lines or ≥5 discrete items → route to `/wogi-extract-review`.
+2. **Item Reconciliation** — ≥3 items → enumerated Item Manifest; unmapped items surface as warnings.
+3. **Consumer Impact Analysis** — refactoring keywords trigger `git grep` for consumers; ≥5 breaking → phased migration recommendation.
+4. **Scope-Confidence Audit** — assumption patterns (`new <X>`, `existing <Y>`) verified against codebase; findings go to Pending Clarifications.
+5. **Intent Bootstrap Coordination** — schedules IGR artifact bootstrap so `/wogi-story` and `/wogi-start` don't both prompt.
 
-**Enforcement**: `scripts/flow-completion-truth-gate.js` → `scanForClaimContradictions()`. Invoked by `flow-session-end.js` and `flow-health.js`.
+All gates fail-open (grep/classifier unavailable → warning, story still created). Bypass for testing via `--skip-gates`. Config: `storyFlow.*`.
 
 ---
 
-### Merge-Plan Artifact Gate
+### Workspace Worker Contract
 
-**Rule**: `/wogi-finalize` requires `.workflow/scratch/merge-plan.md` for any merge with more than `config.finalization.mergePlan.threshold` commits (default 5) OR any cross-repo merge. The plan must map every commit in `git log <base>..<branch>` to one of: `port | adapt | skip-style | superseded | skip-with-reason`.
+*Applies only in workspace worker mode (`WOGI_WORKSPACE_ROOT` set + `WOGI_REPO_NAME !== 'manager'`). Ignore in solo sessions.*
 
-**Mechanical invariant**: count of SHA-prefixed lines in the plan MUST equal `git log <base>..<branch> | wc -l`. Mismatch blocks the merge.
+**Tool-First Turn**: Every turn after `UserPromptSubmit` must contain ≥1 tool call. In strict mode (default), the first assistant content block must be `tool_use`, not text. Pure-text responses are invisible to the user (they only see the manager terminal) and disqualify the worker from the three-state contract below.
 
-**Structural-change sensor**: when ≥ `config.finalization.mergePlan.restructureThreshold` (default 20%) of changed files match a restructure pattern (folder-per-component, split-into-submodule, barrel-introduction, rename-new-home), a structural warning prefixes the plan and biases affected commits toward `adapt`.
+**Three-State End-of-Turn**: Exactly one of:
+1. **ACTION** — start next pre-approved channel dispatch via `/wogi-start <nextId>`.
+2. **ESCALATION** — channel-dispatch `## QUESTION: ...` to the manager.
+3. **IDLE** — zero pending dispatches AND zero in-progress tasks.
 
-**Enforcement**: `scripts/flow-structure-sensor.js`, `.claude/commands/wogi-finalize.md` Step 2.5.
+Hedging phrases ("awaiting your signal", "let me know", "standing by", "should I continue") are mechanically forbidden — visibility is NOT a substitute for action; the manager already pre-approved the dispatch by queuing it.
 
----
+**No direct user prompts**: `AskUserQuestion` is blocked; questions go through channel dispatch as `## QUESTION: ...`. Block message carries the exact `curl` command to use.
 
-### Story Creation Quality Gates
+**Hedging detection**: A Haiku classifier inspects the final message at Stop-hook time; confidence ≥ `minConfidence` → stop is blocked with channel-dispatch instructions. Fail-open on missing API key / transcript / classifier error.
 
-**Rule**: `/wogi-story` enforces five P0 specification-quality gates at creation time. Gates answer *"is the story clear, complete, checkable?"* — NOT *"is the implementation correct?"* (the latter remains `/wogi-start`'s job).
+Enforced by: `worker-tool-first-gate.js` (G1/G4/Gap B), `worker-boundary-gate.js`, `flow-worker-question-classifier.js`. Config: `workspace.toolFirstTurnGate.{enabled,strict}`, `workspace.blockAskUserQuestionInWorker`, `workspace.aiWorkerQuestionClassifier.*`, `workspace.autoPickupChannelDispatches`.
 
-1. **Long Input** — ≥40 lines OR ≥5 discrete items → route to `/wogi-extract-review` for zero-loss capture.
-2. **Item Reconciliation** — ≥3 discrete items → enumerated "Item Manifest" section; every item must appear in at least one criterion or sub-task. Unmapped items surface as a warning.
-3. **Consumer Impact Analysis** — refactoring keywords (`refactor`, `rename`, `migrate`, `split`, `extract`, ...) trigger `git grep` for consumers. ≥5 breaking consumers → phased migration recommendation.
-4. **Scope-Confidence Audit** — assumption patterns (`new <X>`, `existing <Y>`, `the <Z> service`) are verified against the codebase; findings go into a "Pending Clarifications" block.
-5. **Intent Bootstrap Coordination** — schedules IGR artifact bootstrap via `intentBootstrapScheduledAt` flag so `/wogi-story` and `/wogi-start` don't both prompt.
+---
 
-**Guard-rails**: all gates fail-open (grep failure, classifier unavailable → warning, story still created). Gates may be bypassed via `--skip-gates` for testing.
+### Workspace Manager Silent-Halt Detection
 
-**Config**: `storyFlow.consumerImpactAnalysis.*`, `storyFlow.scopeConfidenceAudit.*`, `storyFlow.itemReconciliation.*` in `.workflow/config.json`.
+*Applies only in workspace manager mode. Ignore in solo sessions.*
 
----
+Every manager→worker dispatch is tracked. A pending dispatch past its `expectedDeadline` with no `task-complete` or `worker-stopped` message = silent death, surfaced on the manager's next turn via `UserPromptSubmit` `additionalContext`. Default `expectedDurationMs = 30min`; callers override per-dispatch for long tasks.
+
+Three terminal states: **Completed** (task-complete arrived), **Graceful-stop** (worker-stopped arrived), **Silent-halt** (no message, deadline passed).
 
-### Workspace Autonomous-Mode Action-After-Completion Contract
+Enforced by: `lib/workspace-dispatch-tracking.js`, `.workspace/state/dispatched-tasks.json` (ring buffer, last 100 records). File-based, hook-driven, no background processes.
 
-**Applies to**: workspace worker mode (`WOGI_WORKSPACE_ROOT` set + `WOGI_REPO_NAME !== 'manager'`).
+---
 
-**Rule**: A worker's end-of-turn must be a deterministic action. Exactly one of these states must hold:
+### Main-Mode Question Classifier
 
-1. **ACTION** — started the next pre-approved channel dispatch (invoked `/wogi-start <nextId>`), OR
-2. **ESCALATION** — channel-dispatched a `## QUESTION:` to the manager (after local resolution attempts failed), OR
-3. **IDLE** — zero pending channel dispatches AND zero in-progress tasks.
+*Applies in solo/main-mode sessions with `taskBoundaryReset.enabled: true`.*
 
-**Hedging language is mechanically forbidden**: *"awaiting your signal"*, *"let me know if"*, *"should I continue"*, *"standing by"*, *"ready when you are"*. These invent an imaginary decision point — the manager already pre-approved the dispatch by queuing it. Visibility is NOT a substitute for action; workers narrate AND act in the same turn.
+Before the Stop hook fires SIGTERM for task-boundary restart, a Haiku classifier inspects the final assistant message. If the AI ended the turn with an open user-facing question AND `pending-question.json` is absent, the classifier writes the marker and defers the restart — the user's reply then lands in the same session context. Fail-open throughout.
 
-**Enforcement**: `TaskCompleted` hook emits auto-pickup when queued dispatches exist. `Stop` hook blocks end-of-turn when a worker has queued dispatches but no in-progress task. `worker-rules.md` template carries the 3-state contract.
+**Prefer explicit `flow ask "<question>"`** — it writes the marker directly and runs before the classifier (short-circuits with `pending-question-deferred`). The classifier is the safety net for when you forget.
 
-**Config**: `workspace.autoPickupChannelDispatches` (default `true`).
+Enforced by: `task-boundary-reset.js → consumeAndTriggerRestart()`. Config: `mainModeQuestionClassifier.{enabled,minConfidence,model}`.
 
 ---
 
-### Workspace Worker Cannot Prompt User Directly
+### Main-Mode Auto-Pickup After Clean Restart
 
-**Applies to**: workspace worker mode.
+*Applies in solo/main-mode sessions with `taskBoundaryReset.enabled: true` AND `taskBoundaryReset.autoPickupNextTask: true` (default).*
 
-**Rule**: The `AskUserQuestion` tool is mechanically blocked in worker mode. Questions to the user MUST be channel-dispatched to the manager via `## QUESTION: ...`.
+After a task-boundary restart triggered by a **clean** completion (not error/blocked/killed), the next SessionStart context injects `AUTO-PICKUP MODE ACTIVE` with the next ready task ID. The first user message → invoke `Skill(skill="wogi-start", args="<nextReadyId>")` immediately, regardless of message content. No "what's next?", no summary, no proposing alternatives.
 
-**Why block instead of auto-redirect**: the worker must consciously choose between (a) channel-dispatching the real question to the manager for user input, or (b) making a reasonable autonomous decision and noting it in the task reply. Silent redirection removes that choice.
+**Precedence**: `pending-question.json` (R-336) wins. If the prior session ended with an open question, auto-pickup is skipped even if all other conditions hold.
 
-**Enforcement**: `scripts/hooks/core/worker-boundary-gate.js` → `checkWorkerBoundary()`. PreToolUse hook blocks `AskUserQuestion`; block message includes the exact `curl ... --data-binary "## QUESTION: ..."` command. Config: `workspace.blockAskUserQuestionInWorker` (default `true`).
+**Skip conditions** (any disables; marker still consumed): pending-question exists, `ready.json` empty, `autoPickupNextTask: false`, marker absent.
 
----
+Enforced by: `task-boundary-reset.js → writeCleanCompletionMarker()` + `session-context.js → formatContextForInjection()`. Marker: `.workflow/state/task-boundary-clean-completion.json` (single-use).
 
-### Workspace Worker Text-Question Classifier
+---
 
-**Applies to**: workspace worker mode.
+### Code Quality Patterns (generic)
 
-**Rule**: If a worker ends a turn with a text-based question to the user (no tool call — just hedging: *"let me know"*, *"should I"*, *"which option"*, *"thoughts?"*, trailing `?`), the Stop hook runs a Haiku classifier on the final assistant message. If it detects an open question with confidence ≥ `minConfidence` → stop is blocked with channel-dispatch instructions.
+1. **Single Source of Truth for Constants** — import from one canonical location; never duplicate model/config objects across files.
+2. **Named Constants for Magic Numbers** — define thresholds as named constants (`const COVERAGE_THRESHOLDS = { default: 0.7, comprehensive: 0.85 }`); don't inline literals.
 
-**Why AI instead of regex**: hedging vocabulary is infinite. Regex misses novel phrasings.
+---
 
-**Fail-open throughout**: missing `ANTHROPIC_API_KEY`, missing transcript path, malformed transcript, or model error → skip. Silent-stall false negatives are recoverable; false-positive blocks every turn are not.
+### Regression Discipline
 
-**Enforcement**: `scripts/flow-worker-question-classifier.js`. Config: `workspace.aiWorkerQuestionClassifier.{enabled,minConfidence,model}`.
+Typecheck/lint/build gates catch code errors, NOT behavior drift. For critical user-facing flows (login, submit, approve, delete, invite, etc.):
 
----
+1. **Executable scripts, not test-plan documents** — each flow gets an executable regression artifact (Playwright, Jest integration, curl-scripted e2e) at `regression-suite/<flow>.<ext>`. Test plans rot; scripts fail loudly.
+2. **Living feature inventory** — one table with `Feature | Last Verified | Commit | Regression Script | Known Issues`; update the "Known Issues" cell with the bug's task ID rather than writing separate incident docs.
+3. **Change-touch rule** — when a task modifies a file mapped to a regression script, that script must pass before task close. Enforce per-task via acceptance criteria until a native gate ships.
+4. **Audit-seeded, not human-written** — use `/wogi-audit` to produce a draft inventory from current code, then review row-by-row.
 
-### Workspace Worker Silent-Halt Detection
+Anti-rationalization: *"We don't have regression coverage but I'm confident my fix won't break it"* → WRONG. Confidence is not evidence.
 
-**Applies to**: workspace manager mode.
+---
 
-**Rule**: Every dispatch to a worker MUST be tracked. Any pending dispatch past its `expectedDeadline` with no matching `task-complete` or `worker-stopped` message = silent death, surfaced on the manager's next turn.
+### Memory-First Clarification
 
-**Three terminal states**:
-1. **Completed** — `task-complete` message arrived.
-2. **Graceful-stop** — `worker-stopped` message arrived (worker's Stop hook fired, but didn't complete).
-3. **Silent-halt** — no message, deadline passed. Worker probably dead.
+Before asking the user a product-domain question (role model, business rules, product scope, terminology), check `.workflow/state/product.md`, `domain-model.md`, `user-journeys.md`, `glossary.md` first. Every redundant question costs trust.
 
-**Deadline**: default `expectedDurationMs` = 30 min. Callers override per-dispatch for long tasks.
+When you must ask, cite what you checked: *"I read domain-model.md §Roles; it says X — does this apply to Y too?"* — not *"what's Y?"*
 
-**Architecture — file-based, hook-driven, no background processes**:
-- `lib/workspace-dispatch-tracking.js` — record / reconcile / overdue helpers
-- `.workspace/state/dispatched-tasks.json` — ring buffer of last 100 active records
-- Manager's `dispatchToChannel()` calls `recordDispatch()` after successful POST
-- Manager's `UserPromptSubmit` hook sweeps the message bus and surfaces overdue records as `additionalContext`
+If artifacts don't exist yet, run `node scripts/flow-intent-bootstrap.js bootstrap` (or trigger via `/wogi-start` on any IGR-enabled task). A project without `domain-model.md` is a project where every domain question will be re-asked every session.
 
 ---
 
-### Code Quality Patterns (generic)
+### Autonomous Walk-Away Mode
+
+The user can dump N items, say "go until you finish" / "autonomous mode" / "run this autonomously" / "don't bother me, just do it" (or similar phrases — see `flow-autonomous-detector.js`), and walk away. While the run is active:
 
-These apply to any codebase being built with WogiFlow's help.
+- **productBehavior / ux questions** → append to `.workflow/state/question-queue.json` (do NOT ask the user). Render in the end-of-run summary so the user resolves them in one batch.
+- **engineering / naming / implementation** → decide autonomously, report in the summary.
+- **infrastructure / performance** → decide autonomously, report after.
+- **security** → auto-fix-report-after (existing).
+- **low-confidence technical decisions** → self-adversarial challenge to ≥90% confidence; queue if cap hit. Counter is shared with the IGR Architect-Adversary loop (default cap 30 per run, configurable via `autonomousMode.maxAdversaryInvocations`).
+- **Blocking errors (typecheck/test/conflict)** → fix autonomously; only surface if fundamentally un-fixable.
 
-**1. Single Source of Truth for Constants** — avoid duplicating model/configuration objects across files. Import from one canonical location. Prevents drift and makes updates simpler.
+**Persistence**: the autonomous flag is written to `session-state.json` on disk (canonical) and cached in-process (read-hot). It survives task-boundary SIGTERM restarts via SessionStart re-hydration. Staleness threshold (default 1h via `autonomousMode.stalenessThresholdMs`) covers laptop-sleep and unclean termination — stale flags do NOT auto-resume.
 
-**2. Named Constants for Magic Numbers** — define thresholds and limits as named constants; don't inline literals.
+**Anti-hedging**: while autonomous mode is active, phrases like "let me know if", "should I continue", "awaiting your signal", "standing by", "would you like me to" are forbidden. The user has walked away.
 
-```js
-const COVERAGE_THRESHOLDS = { default: 0.7, comprehensive: 0.85, concise: 0.5 };
-```
+**Exit conditions**: ready queue drains, user types "stop"/"pause", or fatal error. On exit, render the completion summary (terminal block + JSON payload at `.workflow/state/autonomous-run-summary-<runId>.json`) and clear the flag.
 
-Self-documenting; easier to maintain.
+Enforced by: `flow-autonomous-detector.js`, `flow-question-queue.js`, `flow-decision-authority.js` (autonomous param + `queue-for-review` + `adversary-loop` buckets), `flow-completion-summary.js`, and the SessionStart context injection in `scripts/hooks/core/session-context.js`.