wogiflow 2.29.5 → 2.29.7

package/.claude/docs/claude-code-compatibility.md

@@ -77,6 +77,7 @@ flow parallel check  # See available parallel tasks
 | 2.18.0+ | 2.1.108+ | ENABLE_PROMPT_CACHING_1H guidance, /recap awareness, /doctor MCP duplicate-scope mirror in `/wogi-health` |
 | 2.27.0+ | 2.1.116+ | Sandbox dangerous-path safety on auto-allow, agent frontmatter hooks for `--agent`, `/resume` large-session speedup, MCP stdio concurrent startup |
 | 2.27.0+ | 2.1.117+ | Native bfs/ugrep via Bash (hook audit documented), Opus 4.7 /context fix (estimator already percentage-based), Pro/Max effort default shift (advisory delta documented), agent frontmatter `mcpServers` for `--agent`, subagent model-mismatch malware-warning fix, managed-settings plugin marketplace enforcement |
+| 2.29.6+ | 2.1.132+ | Statusline `context_window` token-count accuracy fix (release notes: was reporting cumulative session totals — may have affected `wogi-statusline-setup` percentage presets if percentage was derived from cumulative tokens), Bedrock/Vertex `ENABLE_PROMPT_CACHING_1H` 400-error fix (recommendation now safe on those providers), `CLAUDE_CODE_SESSION_ID` available in Bash subprocess env |
 
 ### Environment Variables (2.1.19+)
 
@@ -368,7 +369,7 @@ await cancelTask('wf-123', 'superseded', false);
 
 ### Features in 2.1.108+
 
-- **`ENABLE_PROMPT_CACHING_1H` env var (RECOMMENDED for non-subscribers)**: Opts into **1-hour prompt-cache TTL** on **API key, Bedrock, Vertex, and Foundry** providers. Subscribers (Claude Pro, Max, Team, Enterprise via claude.ai OAuth) already get 1h TTL by default — this flag is a **no-op for them**. The complementary `FORCE_PROMPT_CACHING_5M` pins to 5min, and the older `ENABLE_PROMPT_CACHING_1H_BEDROCK` is deprecated but still honored. **Impact on WogiFlow (HIGH)**: WogiFlow sessions load a large, stable prefix every turn — CLAUDE.md (~300 lines), state files (`ready.json`, `decisions.md`, `app-map.md`), phase files, and pinned spec context. At the default 5min TTL, any pause longer than 5 minutes (user thinking, a long `flow` CLI run, a meeting mid-session) invalidates the cache and the next turn pays the full input-token cost again. At 1h TTL, the same prefix stays cached across those pauses, yielding **substantial token-cost reduction** on typical multi-hour WogiFlow work. **Action for API-key / Bedrock / Vertex / Foundry users**: `export ENABLE_PROMPT_CACHING_1H=1` in your shell profile. **Action for subscribers**: none (already enabled). **Risk**: none — if set on a subscriber account it is ignored; if set when not supported, it silently falls back.
+- **`ENABLE_PROMPT_CACHING_1H` env var (RECOMMENDED for non-subscribers)**: Opts into **1-hour prompt-cache TTL** on **API key, Bedrock, Vertex, and Foundry** providers. Subscribers (Claude Pro, Max, Team, Enterprise via claude.ai OAuth) already get 1h TTL by default — this flag is a **no-op for them**. The complementary `FORCE_PROMPT_CACHING_5M` pins to 5min, and the older `ENABLE_PROMPT_CACHING_1H_BEDROCK` is deprecated but still honored. **Impact on WogiFlow (HIGH)**: WogiFlow sessions load a large, stable prefix every turn — CLAUDE.md (~300 lines), state files (`ready.json`, `decisions.md`, `app-map.md`), phase files, and pinned spec context. At the default 5min TTL, any pause longer than 5 minutes (user thinking, a long `flow` CLI run, a meeting mid-session) invalidates the cache and the next turn pays the full input-token cost again. At 1h TTL, the same prefix stays cached across those pauses, yielding **substantial token-cost reduction** on typical multi-hour WogiFlow work. **Action for API-key / Bedrock / Vertex / Foundry users**: `export ENABLE_PROMPT_CACHING_1H=1` in your shell profile. **Action for subscribers**: none (already enabled). **Risk**: none — if set on a subscriber account it is ignored; if set when not supported, it silently falls back. **Bedrock/Vertex caveat**: Some Claude Code versions before 2.1.132 returned 400 errors when this flag was set on Bedrock/Vertex (per the 2.1.132 release notes). Fixed in **2.1.132+** — Bedrock/Vertex users on older Claude Code should upgrade before setting the flag.
 
 - **`/recap` command and session recap feature**: Provides context when returning to a session. Configurable in `/config` and manually invocable with `/recap`. For users with telemetry disabled (Bedrock/Vertex/Foundry/`DISABLE_TELEMETRY`), recap is still enabled by default; opt out via `/config` or `CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0`. **Overlap with WogiFlow**: `/wogi-morning`, `/wogi-session-end`, and `/wogi-pre-compact` already provide durable recap via state files. `/recap` is ephemeral (summarizes the current session); WogiFlow's state survives session exit. Use both: `/recap` for intra-session context, `/wogi-morning` for cross-session pickup.
 

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

@@ -148,53 +148,37 @@ When in doubt, route through `/wogi-start` which will classify correctly.
 
 ### Anti-Deferral Rule (MANDATORY — ZERO TOLERANCE)
 
-**You MUST NEVER autonomously defer, skip, deprioritize, or drop items from the user's input.**
+**You MUST NEVER autonomously defer, skip, deprioritize, or drop items from the user's input.** If the user provides N items, ALL N become tracked work items. No judgment calls about "important" vs. "enhancement" vs. "long-term."
 
-If the user provides N items, ALL N must become tracked work items. No exceptions. No judgment calls about what's "important" vs. "enhancement" vs. "long-term."
+**Deferral-specific traps** (in addition to master Anti-Rationalization Checklist above):
+- "Items 6-9 are enhancements, I'll focus on fixes first" → WRONG. Create tasks for ALL items.
+- "I already created the important ones" → WRONG. Important is not your call.
+- "I'll defer these as lower priority" → WRONG. Suggest priority; every item still gets a task.
+- "The ready queue would be too large" → WRONG. A large queue is correct; a filtered queue is data loss.
+- "This one was labeled 'long-term'" → WRONG. The user decides when to execute, not you.
 
-**Anti-Deferral Checklist** — If ANY of these thoughts cross your mind, you are about to drop items:
-- "Items 6-9 are enhancements, I'll focus on the fixes first" → WRONG. Create tasks for ALL items.
-- "This one was labeled 'long-term' by the team" → WRONG. Track it. The user decides when to execute, not you.
-- "I'll defer these as lower priority" → WRONG. You may SUGGEST a priority order, but every item must be a tracked task.
-- "The ready queue would be too large" → WRONG. A large queue is correct. A filtered queue is data loss.
-- "I already created the important ones" → WRONG. Important is not your call. Create ALL of them.
+**MAY**: suggest priority order (P0/P1/P2/P3); group related items into stories (every item appears as a criterion in ≥1 story); ask the user to confirm scope.
 
-**What you MAY do:**
-- Suggest a priority order (P0/P1/P2/P3) — but ALL items get tasks regardless of priority
-- Group related items into stories — but every item must appear as a criterion in at least one story
-- Ask the user to confirm scope — but do NOT preemptively filter
+**MUST NEVER**: silently drop items based on AI judgment; create tasks for a subset without explicit user approval to defer the rest; use words like "deferred"/"skipped"/"not created" for user-provided items.
 
-**What you must NEVER do:**
-- Silently drop items because you judged them as "enhancements" or "nice-to-haves"
-- Create tasks for only a subset of items without explicit user approval to defer the rest
-- Use words like "deferred", "skipped", or "not created" for items the user provided
+Applies to `/wogi-start`, `/wogi-story`, `/wogi-epics`, `/wogi-extract-review`, and any command converting user input into tracked work.
 
-**This rule applies everywhere**: `/wogi-start`, `/wogi-story`, `/wogi-epics`, `/wogi-extract-review`, and any other command that converts user input into tracked work.
+### Mid-Execution Anti-Deferral (AFTER TASKS ARE CREATED)
 
-### Mid-Execution Anti-Deferral (MANDATORY — APPLIES AFTER TASKS ARE CREATED)
+**Reordering is permitted. Deferring is not.** Once work is tracked, you MUST NOT propose to skip, postpone, drop, or "deprioritize to later" — regardless of risk, cost, or token-weight. Only sequence changes. "Revisit later" and "deprioritize" are soft-defer euphemisms.
 
-**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.
+When genuinely unsure work is still needed: ask explicitly — "Do you still want wf-XXXX to ship this epic, or drop it?" User decides.
 
-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.
-
-**MAY do after tasks are tracked**: propose sequence/parallelization/prerequisites; flag risks without using them to drop scope.
-
-**MUST NEVER do**: propose to "defer", skip based on AI judgment, present a plan that silently omits tracked work.
-
-**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)
+### Review-Findings Anti-Deferral
 
 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 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.
-
-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.
+2. Never silently convert a finding to "deferred" in commit/release notes without the user saying "defer X."
+3. If too large for the current release → STOP and ask: "Finding X requires ~Y min. Ship / split / defer?"
+4. Never list a finding in release notes without actually fixing it.
 
-**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.
+"Low-risk can wait" and "restructure warrants separate release" are AI judgment calls — the user's to make.
 
 ### Task ID Format (MANDATORY)
 

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

@@ -1,24 +1,20 @@
 ## WogiFlow Methodology Rules
 
-Product-level rules enforced by shipped hooks. Text below exists so Claude understands the contract, not as the enforcement mechanism itself.
+Rules below are enforced by shipped hooks; the prose is so Claude understands the contract. Apply the master Anti-Rationalization Checklist (top of CLAUDE.md) to any rule that doesn't list its own.
 
 ---
 
 ### Research Before Propose
 
-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.
+Before proposing a fix, plan, or spec, read 2+ files from `.workflow/state/`, `.workflow/changes/`, `.workflow/specs/`, or `.workflow/epics/`. Clarifying questions are a valid escape; proposing without evidence is not.
 
-You MAY ask clarifying questions (valid escape hatch). You may NOT propose without evidence.
-
-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`).
+Enforced by: `research-evidence-gate.js` (blocks `→ spec_review` / `→ coding` and spec-file writes until threshold met). Config: `hooks.rules.researchEvidenceGate.{enabled,minEvidence}` (defaults `true`, `2`).
 
 ---
 
 ### Completion-Claim Honesty Scan
 
-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.
+At session-end and `flow health`, `ready.json` entries are scanned (surfaced, not blocked) for status-mismatch (free-text says "done" while `status` is partial/blocked) and negation-vs-evidence (free-text says "no outages" while `hotfixes[]`/`incidents[]`/`regressions[]` is non-empty).
 
 Enforced by: `flow-completion-truth-gate.js → scanForClaimContradictions()`.
 
@@ -26,7 +22,7 @@ Enforced by: `flow-completion-truth-gate.js → scanForClaimContradictions()`.
 
 ### 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`.
+`/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 = commit count. ≥20% restructure-pattern files biases affected commits toward `adapt`.
 
 Enforced by: `flow-structure-sensor.js`, `.claude/commands/wogi-finalize.md` Step 2.5.
 
@@ -34,58 +30,46 @@ Enforced by: `flow-structure-sensor.js`, `.claude/commands/wogi-finalize.md` Ste
 
 ### Story Creation Quality Gates
 
-`/wogi-story` runs 5 P0 spec-quality gates at creation time (not implementation-correctness gates — that's `/wogi-start`'s job):
+`/wogi-story` runs 5 P0 spec-quality gates at creation time:
 
-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.
+1. **Long Input** — ≥40 lines or ≥5 items → route to `/wogi-extract-review`.
+2. **Item Reconciliation** — ≥3 items → enumerated Item Manifest; unmapped items warn.
+3. **Consumer Impact Analysis** — refactoring keywords trigger `git grep`; ≥5 breaking → phased migration.
+4. **Scope-Confidence Audit** — assumption patterns verified against codebase; findings → Pending Clarifications.
+5. **Intent Bootstrap Coordination** — schedules IGR bootstrap once.
 
-All gates fail-open (grep/classifier unavailable → warning, story still created). Bypass for testing via `--skip-gates`. Config: `storyFlow.*`.
+All fail-open. Bypass for tests via `--skip-gates`. Config: `storyFlow.*`.
 
 ---
 
 ### Workspace Worker Contract
 
-*Applies only in workspace worker mode (`WOGI_WORKSPACE_ROOT` set + `WOGI_REPO_NAME !== 'manager'`). Ignore in solo sessions.*
-
-**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.
-
-**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.
-
-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.
+*Workspace worker mode only (`WOGI_WORKSPACE_ROOT` set + `WOGI_REPO_NAME !== 'manager'`). Skip in solo sessions.*
 
-**No direct user prompts**: `AskUserQuestion` is blocked; questions go through channel dispatch as `## QUESTION: ...`. Block message carries the exact `curl` command to use.
+- **Tool-First Turn**: every turn after `UserPromptSubmit` must contain ≥1 tool call. In strict mode (default), the first content block must be `tool_use`. Pure-text responses are invisible to the user.
+- **Three-State End-of-Turn**: exactly one of ACTION (`/wogi-start <nextId>`), ESCALATION (channel-dispatch `## QUESTION:`), or IDLE.
+- **Hedging forbidden**: "awaiting your signal", "let me know", "standing by", "should I continue".
+- **No direct user prompts**: `AskUserQuestion` is blocked; questions go through channel dispatch.
 
-**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.
-
-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`.
+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.*`. Long-form: `.claude/rules/_internal/worker-tool-first-turn.md`.
 
 ---
 
 ### Workspace Manager Silent-Halt Detection
 
-*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.
+*Workspace manager mode only.*
 
-Three terminal states: **Completed** (task-complete arrived), **Graceful-stop** (worker-stopped arrived), **Silent-halt** (no message, deadline passed).
+Every manager→worker dispatch is tracked. A pending dispatch past `expectedDeadline` with no `task-complete`/`worker-stopped` = silent halt, surfaced on next turn via `UserPromptSubmit` `additionalContext`. Default `expectedDurationMs = 30min`. Three terminal states: Completed / Graceful-stop / Silent-halt.
 
-Enforced by: `lib/workspace-dispatch-tracking.js`, `.workspace/state/dispatched-tasks.json` (ring buffer, last 100 records). File-based, hook-driven, no background processes.
+Enforced by: `lib/workspace-dispatch-tracking.js`, `.workspace/state/dispatched-tasks.json` (ring buffer, last 100).
 
 ---
 
 ### Main-Mode Question Classifier
 
-*Applies in solo/main-mode sessions with `taskBoundaryReset.enabled: true`.*
-
-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.
+*Solo sessions with `taskBoundaryReset.enabled: true`.*
 
-**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.
+Before Stop hook fires SIGTERM, a Haiku classifier inspects the final assistant message. Open user-facing question + no `pending-question.json` → write marker, defer restart. Prefer explicit `flow ask "<question>"` (writes marker directly, short-circuits the classifier). Fail-open throughout.
 
 Enforced by: `task-boundary-reset.js → consumeAndTriggerRestart()`. Config: `mainModeQuestionClassifier.{enabled,minConfidence,model}`.
 
@@ -93,123 +77,130 @@ Enforced by: `task-boundary-reset.js → consumeAndTriggerRestart()`. Config: `m
 
 ### Main-Mode Auto-Pickup After Clean Restart
 
-*Applies in solo/main-mode sessions with `taskBoundaryReset.enabled: true` AND `taskBoundaryReset.autoPickupNextTask: true` (default).*
+*Solo sessions with `taskBoundaryReset.enabled: true` AND `autoPickupNextTask: true` (default).*
 
-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.
+After a clean-completion task-boundary restart, SessionStart context injects `AUTO-PICKUP MODE ACTIVE` with the next ready task ID. First user message → invoke `Skill(skill="wogi-start", args="<nextReadyId>")` immediately, regardless of message content.
 
-**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.
+Precedence: `pending-question.json` wins. Skip conditions (any disables): pending-question exists, ready empty, autoPickup off, marker absent.
 
-**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).
+Enforced by: `task-boundary-reset.js → writeCleanCompletionMarker()` + `session-context.js`. Marker: `.workflow/state/task-boundary-clean-completion.json` (single-use).
 
 ---
 
-### Code Quality Patterns (generic)
+### Code Quality Patterns
 
-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.
+1. **Single source of truth for constants** — import from one canonical location.
+2. **Named constants for magic numbers** — define thresholds as named constants; don't inline literals.
 
 ---
 
 ### Regression Discipline
 
-Typecheck/lint/build gates catch code errors, NOT behavior drift. For critical user-facing flows (login, submit, approve, delete, invite, etc.):
+Typecheck/lint/build catches code errors, not behavior drift. For critical user-facing flows (login, submit, approve, delete, invite):
 
-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.
+1. Executable scripts at `regression-suite/<flow>.<ext>`, not test-plan documents.
+2. Living feature inventory: `Feature | Last Verified | Commit | Regression Script | Known Issues`.
+3. Change-touch rule: task modifying a file mapped to a regression script must pass that script before close.
+4. Audit-seeded inventory via `/wogi-audit`, then human-reviewed.
 
-Anti-rationalization: *"We don't have regression coverage but I'm confident my fix won't break it"* → WRONG. Confidence is not evidence.
+"Confident my fix won't break it" is not evidence.
 
 ---
 
 ### Memory-First Clarification
 
-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.
-
-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?"*
-
-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.
+Before asking a product-domain question, check `.workflow/state/{product,domain-model,user-journeys,glossary}.md`. When you must ask, cite what you read: *"I read domain-model.md §Roles; it says X — does this apply to Y too?"* not *"what's Y?"*. If artifacts don't exist, run `node scripts/flow-intent-bootstrap.js bootstrap`.
 
 ---
 
 ### Source Fidelity Rule (Verbatim Source Preservation)
 
-When a long-form user request becomes a spec, channel-dispatch message, or any artifact that downstream actors will execute, the **verbatim source MUST be preserved alongside the structured derivation**.
+When a long-form user request becomes a spec or channel-dispatch, the **verbatim source MUST be preserved alongside the structured derivation**. The lossy step is at the spec-authoring layer (manager summarizing user input); downstream actors then build the summary, missing items the user named.
 
-The lossy step in cross-session/cross-worker compression is almost always at the spec-authoring layer (manager summarizing user input into a "contract"). Downstream actors then build the summary's interpretation, missing items the user explicitly named. Adversary checks won't catch this because the adversary sees only the spec, not the original prompt.
+Mandatory structure for any spec/dispatch derived from a long user prompt (>40 lines OR ≥5 items):
 
-**Mandatory structure for any spec or dispatch derived from a long user prompt** (>40 lines OR ≥5 discrete items):
+1. **`## Original Request (verbatim)`** — user's prompt unmodified, top of spec body.
+2. **`## Item Manifest`** — enumerated list reconciling every source item to a specific AC OR an explicit `defer-with-reason: <user-cited reason>`. AI-judged "low priority" is not a valid reason.
+3. **Channel-dispatch links the spec, not summarizes it** — manager-to-worker messages MUST include verbatim source OR a path to a saved spec containing it. Bare "summary contracts" are forbidden.
 
-1. **`## Original Request (verbatim)` block** — the user's prompt unmodified. Required at the top of the spec body.
+Enforced by: Logic Constitution v3 sub-principle 11.6. Adversary blocks specs missing the block when source qualifies. Verifier: `node scripts/flow-source-fidelity.js check <spec-file>`. Worker fallback: `scripts/hooks/core/long-input-enforcement.js`.
 
-2. **`## Item Manifest` block** — enumerated list reconciling every source item to either:
-   - A specific AC in the spec, OR
-   - An explicit `defer-with-reason: <user-cited reason>` entry. The deferral is the user's call, not the AI's. AI-judged "low priority" is NOT a valid reason.
+---
+
+### Cross-Story Integration Tier-3 Rule
 
-3. **Channel-dispatch links the spec, not summarizes it.** Manager-to-worker channel messages that create work MUST include either the verbatim source OR a path to a saved spec file containing the verbatim source. Bare "summary contracts" sent without source link are forbidden.
+When Story B layers on infrastructure shipped by Story A, Story B's IGR pass MUST treat that infrastructure as an audited dependency. Within-module unit tests don't verify Story A's contract holds for Story B's usage.
 
-**Why this rule exists:** the 2026-04-27 wogi-hub Customers > Services incident — user provided a ~50-line spec for a UI page; manager compressed into a 5-bullet "owner-locked decisions" channel-dispatch message; downstream FE worker built the bullet contract literally; result was 5 of 12 user-named features built. The build looked locally correct but didn't match the user's actual ask. Three existing safeguards all failed to catch it: long-input gate (output rolled up, not preserved as canonical), feature dossier (didn't exist for this feature — chicken-and-egg), anti-deferral rule (text only, no mechanical enforcement at spec-write time).
+Mandatory for layering stories:
 
-**Anti-rationalization checklist** — if any of these thoughts cross your mind, you are about to violate the rule:
-- *"I've captured the key decisions in N bullets"* → WRONG. Items the user named are not yours to filter.
-- *"The downstream worker doesn't need the full prompt; the spec is enough"* → WRONG. The spec is YOUR interpretation. The worker should be able to verify against source.
-- *"The user's prompt was rambling; my summary is cleaner"* → WRONG. Cleanliness is not authority to filter user-named items.
-- *"This is just an internal manager message; the user won't see it"* → WRONG. That's exactly when the lossy step happens; verbatim preservation is more important here, not less.
-- *"The long-input gate already extracted the items"* → WRONG IF you don't pin its output as canonical and reconcile every spec against it.
+1. **Architect names upstream dependencies** — "Dependencies" section listing prior stories/commits + the specific contract relied on (interface, file format, transport, invariant). Quote the contract.
+2. **Adversary challenges the dependency** — "What if Story A's invariant doesn't hold? What evidence proves the contract is intact for THIS usage?"
+3. **At least one Tier-3 integration test** exercises the chain end-to-end. Mark `// regression-tier3`.
+4. **Pre-release gate** verifies stacked coverage. Missing Tier-3 + stacked stories → block release.
 
-**Enforcement:** Logic Constitution v3 sub-principle 11.6 (Temporal Source Coverage). Adversary verifies every spec against its `Original Request (verbatim)` block before approval. Specs missing the block when source qualifies for it → BLOCKED at spec_review approval. Verifier CLI: `node scripts/flow-source-fidelity.js check <spec-file>`. Worker-side fallback: `scripts/hooks/core/long-input-enforcement.js` injects forcing instruction at UserPromptSubmit when channel-dispatch arrives long-form without source-link.
+Apply: `git log --oneline <prior-N-commits>` to identify dependencies; for each, write the contract; `grep -r "<interface>"` to verify HEAD; write the Tier-3 test BEFORE Story B's code.
+
+Enforced by: Logic Constitution v3 sub-principle 11.5. Pre-release gate consumes this signal before tagging.
 
 ---
 
-### Cross-Story Integration Tier-3 Rule
+### Autonomous Walk-Away Mode
+
+User says "go until you finish" / "autonomous mode" / "run this autonomously" / "don't bother me, just do it" → flag activates, AI runs without interruption. While active:
+
+- **productBehavior / ux** → append to `.workflow/state/question-queue.json` (do NOT ask). Render in end-of-run summary.
+- **engineering / naming / implementation** → decide autonomously, report in summary.
+- **infrastructure / performance** → decide autonomously, report after.
+- **security** → auto-fix-report-after.
+- **low-confidence technical decisions** → self-adversarial challenge to ≥90% confidence; queue if cap hit. Counter shared with IGR Architect-Adversary loop (default cap 30, `autonomousMode.maxAdversaryInvocations`).
+- **Blocking errors** → fix autonomously; surface only if fundamentally un-fixable.
 
-When Story B layers behavior on top of infrastructure shipped by Story A (or any prior commit), Story B's IGR pass MUST treat that infrastructure as an audited dependency, not as a given. Within-module unit tests that pin Story B's local behavior do NOT verify that Story A's contract holds for Story B's usage.
+Persistence: flag in `session-state.json`, survives task-boundary SIGTERM via SessionStart re-hydration. Staleness threshold (`autonomousMode.stalenessThresholdMs`, default 1h) — stale flags don't auto-resume.
 
-**Mandatory for every layering story:**
+Anti-hedging while active: "let me know if", "should I continue", "awaiting your signal", "standing by", "would you like me to" are forbidden.
 
-1. **Architect output names upstream dependencies.** A "Dependencies" section lists prior stories/commits + the specific contract relied on (interface signature, file format, transport, invariant). "I'm reusing Story A's X" is not enough; quote the contract.
+Exit: ready drains, user types "stop"/"pause", or fatal error. On exit, render completion summary (`.workflow/state/autonomous-run-summary-<runId>.json`) and clear flag.
 
-2. **Adversary challenges the dependency.** "What if Story A's invariant doesn't hold? What's the failure mode? What evidence proves Story A's contract is intact for THIS usage?" The adversary's job is finding the assumption Story B silently inherits.
+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`, SessionStart context in `session-context.js`.
 
-3. **At least one Tier-3 integration test exercises the chain end-to-end.** Not a unit test of Story B in isolation — a test that simulates a real run through both stories' code paths. If Story A's output flows into Story B's input, the test feeds a real Story-A output through Story B and asserts the output. Mark the test `// regression-tier3` so future readers know its purpose.
+---
+
+### Mechanical Deferral Authorization Gate (wf-f9912af6)
+
+The Review-Findings Anti-Deferral rule is enforced mechanically. The PreToolUse hook intercepts every Write/Edit/Bash that targets `.workflow/state/last-review.json` or `last-audit.json` and BLOCKS the write when:
 
-4. **Pre-release gate verifies stacked coverage.** Before tagging a release, identify any commits that layer on prior commits in the same release. For each, confirm a Tier-3 integration test exists. Missing Tier-3 + stacked stories → block release.
+1. New content introduces a finding with `status` matching `/^deferred(?:[-_].*)?$|^wont-?fix$|^skipped$/i`, AND
+2. No valid auth marker at `.workflow/state/deferral-authorization.json`, AND
+3. `no-defer-pin.json` is not active.
 
-**Why:** unit tests within a story boundary catch the story's own bugs but miss every regression where the story's correct behavior depends on a broken upstream. The 2026-04-26 incident (audit-channel-transport-001) was caused by exactly this gap: Story A stripped MCP servers including the workspace-channel transport itself; Story B layered task-completion routing on top; both stories' tests passed; manager dispatch silently failed in production. Self-IGR caught Story B's local correctness but missed that the upstream contract was broken.
+**Authorization sources**:
+- **User-prompt classifier** — regex-detects defer phrases ("defer X", "fix critical only", "ship as-is", "option 2/4"). Auth TTL 10min.
+- **Explicit CLI** — `node scripts/flow-defer-auth.js grant --scope=all --reason="<verbatim user phrase>"`.
 
-**Anti-rationalization:**
-- *"The upstream story has its own tests"* → WRONG. Their tests pin THEIR contract. Your Tier-3 test pins YOUR usage of their contract.
-- *"It's expensive to set up an integration test"* → WRONG. The 2026-04-26 incident cost a v2.29.1 hot-fix release. Set up time amortizes; regression cost compounds.
-- *"Self-IGR is enough; we don't need the actual adversary subagent"* → WRONG. Self-IGR pattern-matches on the same model that wrote the plan; the cross-story dependency is exactly the blind spot a different-model adversary catches.
+**Negative intent overrides positive**: "fix everything", "no deferrals", "I don't want tech debt" delete auth and write `no-defer-pin.json` (~30min hard-block).
 
-**How to apply** (concrete checks for any layering story):
-- `git log --oneline <prior-N-commits>` — which earlier work does this story sit on?
-- For each, write the contract you're relying on: "Story A delivers X via Y."
-- `grep -r "<Story A's interface>"` — is the contract still intact in HEAD?
-- Write the Tier-3 test BEFORE writing Story B's code. If the test cannot be written without first standing up infrastructure that makes the integration verifiable, that's a signal the architecture needs that infrastructure too.
+**Bash-mutating commands** that target review/audit files AND mention `deferred|wont-fix|skipped|dismissed` are blocked when no auth is active. Reads (cat/jq/grep) pass.
 
-Enforced by: Logic Constitution v3 sub-principle 11.5 (Stacked-story integration verification). Pre-release gate consumes this signal before tagging.
+Audit trail: `.workflow/state/deferral-block-log.json` (last 100). Config: `deferralGate.{enabled,authTtlSeconds,classifyUserPrompts}` (defaults true / 600 / true).
+
+Enforced by: `scripts/hooks/core/deferral-gate.js`, `deferral-classifier.js`, `scripts/flow-defer-auth.js`, wired into `pre-tool-orchestrator.js` and `user-prompt-submit.js`.
 
 ---
 
-### Autonomous Walk-Away Mode
+### Mechanical Research-Required Gate (wf-5cd71b1f)
 
-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:
+Diagnostic prompts are intercepted at UserPromptSubmit and re-prompted at Stop hook if the assistant turn produced text without enough Read calls against evidence paths.
 
-- **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.
+Flow:
 
-**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.
+1. **Classifier** (`research-required-classifier.js`) classifies each prompt: `command` / `factual` / `diagnostic` / `none`. Diagnostic markers: "why", "should I", "what do you think", "is this correct", "explain why", "did you fix". On diagnostic → write `.workflow/state/research-required-this-turn.json` with `{requiredEvidence: 2, attemptCount: 0}`.
+2. **Override**: prompt prefix `!` skips the gate.
+3. **Stop-hook gate** (`research-required-gate.js`) parses the JSONL transcript, counts Read against evidence prefixes, Bash with `cat|head|tail|grep|rg|jq|less|view|awk|sed` against evidence paths, and any Glob/Grep.
+4. **count < required** → `{continue: true, stopReason: <message>}` forces redo. After `maxAttempts` (default 3) → hard-stop visible to user.
+5. **count ≥ required** → marker consumed, Stop proceeds.
 
-**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.
+Evidence prefixes: `.workflow/state/`, `.workflow/changes/`, `.workflow/specs/`, `.workflow/epics/`, `lib/`, `scripts/`, `src/`, `tests/`, `app/`.
 
-**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.
+Config: `researchRequiredGate.{enabled,requiredEvidence,maxAttempts}` (defaults true / 2 / 3). Override prefix `!` is hard-coded.
 
-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`.
+Enforced by: `research-required-classifier.js` (UserPromptSubmit), `research-required-gate.js` (Stop), wired into `user-prompt-submit.js` and `stop.js`.

package/README.md

@@ -1,6 +1,6 @@
 # WogiFlow
 
-A self-improving AI development workflow that learns from your feedback. Currently supports **Claude Code 2.1.33+**.
+A self-improving AI development workflow that learns from your feedback. Currently supports **Claude Code 2.1.33+**. Claude Code **2.1.121+** is recommended for native MCP startup retries (transient channel-server failures auto-recover), Bash resilience to deleted CWDs (worktree cleanup is safe mid-session), and `Always allow` permission persistence across worker restarts.
 
 ```bash
 npm install -D wogiflow

package/lib/wogi-claude

@@ -21,6 +21,12 @@
 #   WOGI_MAX_RESTARTS    — safety cap, default 50 (prevents runaway restart storms)
 #   WOGI_WRAPPER_PID     — exported to child; hook checks this to confirm wrapper is present
 #   WOGI_CLAUDE_BIN      — override path to claude binary (default: found via PATH)
+#   WOGI_BASH_BIN        — (wf-ee4e343b cleanup) override the bash binary used
+#                          by the PID-alignment subshell trick. Defaults to
+#                          `bash` on PATH. Useful on minimal containers
+#                          (Alpine, distroless) where bash lives at a
+#                          non-standard path or where the shell wrapping the
+#                          claude CLI is not bash-by-default.
 #   WOGI_USE_EXPECT      — (EXPERIMENTAL, v2.22.4+) set to 1 to opt IN to the
 #                          expect-based auto-dismiss of the "Loading development
 #                          channels" dialog. OFF BY DEFAULT because Ink's
@@ -99,7 +105,7 @@ if [ "$__wogi_is_worker" -eq 1 ]; then
       try {
         const cfg = require(process.cwd() + "/.workflow/config.json");
         process.stdout.write(String(!!(cfg.workspace && cfg.workspace.inheritClaudeAiMcpIntegrations)));
-      } catch (_e) { process.stdout.write("false"); }
+      } catch (_err) { process.stdout.write("false"); }
     ' 2>/dev/null)"
     if [ "$__wogi_config_inherit" = "true" ]; then
       __wogi_strip_mcp=0
@@ -205,7 +211,7 @@ if [ "$__wogi_strip_mcp" -eq 1 ]; then
             const ws = cfg && cfg.mcpServers && cfg.mcpServers["wogi-workspace-channel"];
             if (ws) channelEntry = ws;
           }
-        } catch (_e) {}
+        } catch (_err) {}
         const payload = channelEntry
           ? { mcpServers: { "wogi-workspace-channel": channelEntry } }
           : { mcpServers: {} };
@@ -284,12 +290,37 @@ __wogi_build_argv() {
 
 # run_claude — invoke claude, routing through expect when we can auto-dismiss
 # the dev-channels dialog. Preserves stdin/stdout/stderr exactly.
+#
+# wf-ee4e343b: PID-alignment via bash-c-exec trick. The Stop hook's SEC-006
+# check (task-boundary-reset.js:200-206) requires WOGI_WRAPPER_PID === process.ppid
+# in any hook running under claude. Plain `"$CLAUDE_BIN" ...` without `exec`
+# causes bash to fork: claude gets a NEW PID that does not match $$ (this bash
+# wrapper's PID). The check then fails silently, breaking auto-restart for
+# everyone since 2026-04-26.
+#
+# Fix: spawn claude through `bash -c '...'` which forks a fresh bash with its
+# OWN $$, sets WOGI_WRAPPER_PID to that $$, then `exec` replaces the new bash
+# with claude — preserving the same PID. Result: claude's PID equals the
+# WOGI_WRAPPER_PID it inherits, and process.ppid in any hook child of claude
+# equals that same value. The strict-equality SEC-006 check now holds.
+#
+# Why `bash -c` and not a `( ... )` subshell: in bash 3.x (macOS system bash),
+# `$$` inside a `( ... )` subshell returns the OUTER shell's PID, not the
+# subshell's own PID. Bash 4+ adds $BASHPID for that purpose, but we cannot
+# rely on bash 4+ being installed. `bash -c` always returns its own PID via
+# `$$`, regardless of version.
+#
+# Bash -c argv form: `bash -c COMMAND COMMAND_NAME ARG1 ARG2 ...` — COMMAND_NAME
+# becomes $0 inside the script and ARG1..N become $1..$N, so `exec "$0" "$@"`
+# invokes claude with all original args without quoting hazards.
+#
+# For expect mode, the same alignment is performed inside wogi-claude-expect.exp.
 run_claude() {
   __wogi_build_argv "$@"
   if [ "$__wogi_use_expect" -eq 1 ]; then
     expect "$WOGI_EXPECT_SCRIPT" "$CLAUDE_BIN" "${__wogi_claude_argv[@]+"${__wogi_claude_argv[@]}"}"
   else
-    "$CLAUDE_BIN" "${__wogi_claude_argv[@]+"${__wogi_claude_argv[@]}"}"
+    "${WOGI_BASH_BIN:-bash}" -c 'export WOGI_WRAPPER_PID=$$; exec "$0" "$@"' "$CLAUDE_BIN" "${__wogi_claude_argv[@]+"${__wogi_claude_argv[@]}"}"
   fi
 }
 

package/lib/wogi-claude-expect.exp

@@ -90,12 +90,37 @@ set claude_bin [lindex $argv 0]
 set claude_args [lrange $argv 1 end]
 
 # Spawn claude in a pseudo-TTY so its Ink UI renders normally.
-# Use {*} list-splice rather than `eval spawn` — `eval` reparses its
-# arguments as Tcl script, which lets an argument containing bracket syntax
-# (e.g. `[exec attacker-cmd]`) escape to command execution. The splice form
-# expands the list without reparsing.
+#
+# wf-ee4e343b PID-alignment: spawn claude through `bash -c` so we can
+# re-export WOGI_WRAPPER_PID=$$ (the subshell's PID) before exec — this
+# makes claude inherit a WOGI_WRAPPER_PID equal to its own PID, satisfying
+# the SEC-006 strict-equality check in task-boundary-reset.js. Without this,
+# expect's spawn gives claude a PID different from WOGI_WRAPPER_PID and the
+# Stop-hook restart trigger silently fails.
+#
+# The bash -c form `bash -c COMMAND COMMAND_NAME ARG1 ARG2 ...` makes
+# COMMAND_NAME = $0 and the remaining args = $1..$N, so we use `exec "$0" "$@"`
+# to invoke claude with all original args — no quoting hazards.
 _wogi_boot_mark "before spawn"
-spawn $claude_bin {*}$claude_args
+
+# F4 fix (wf-ee4e343b cleanup): defensive list construction. `lrange $argv 1
+# end` already returns a clean Tcl list, and `{*}$claude_args` splices it
+# without re-parsing element contents — so brace-containing args are
+# preserved as single elements. The Sonnet review flagged this as a quoting
+# hazard; the Opus adversary verified it's safe. We rebuild the list
+# explicitly via [list ...] anyway for defense-in-depth and to make the
+# safety property obvious to future readers (no implicit dependency on
+# lrange's return contract).
+set claude_args_safe [list]
+foreach _arg $claude_args { lappend claude_args_safe $_arg }
+
+# Honor WOGI_BASH_BIN (wf-ee4e343b cleanup) for non-standard shell layouts.
+set _wogi_bash_bin "bash"
+if {[info exists env(WOGI_BASH_BIN)] && $env(WOGI_BASH_BIN) ne ""} {
+    set _wogi_bash_bin $env(WOGI_BASH_BIN)
+}
+
+spawn $_wogi_bash_bin -c "export WOGI_WRAPPER_PID=\$\$; exec \"\$0\" \"\$@\"" $claude_bin {*}$claude_args_safe
 _wogi_boot_mark "after spawn (pid=$spawn_id)"
 
 # ============================================================================