wogiflow 2.25.1 → 2.26.1

package/.claude/commands/wogi-session-end.md

@@ -13,7 +13,7 @@ Steps:
 6. **Completion-claim honesty scan** - Surface done-in-text-but-not-in-status contradictions (2026-04-16 honesty-infra)
 7. **Workspace session-end message (v2.23.0+)** - If running inside a workspace manager, write a `heads-up` message to `.workspace/messages/` so workers know no new dispatches are coming
 8. **Commit changes** - Stage and commit all workflow files
-9. **Offer to push** - Ask if should push to remote
+9. **Offer to push** - Ask if should push to remote. In workspace worker mode, the prompt is suppressed (workers cannot prompt the user directly). When `config.sessionEnd.autoPushInWorker` is `true` (default), the worker auto-pushes silently. When `false`, the push is skipped and the user pushes manually later. Non-worker sessions are unchanged.
 
 Output:
 ```

package/.claude/docs/phases/05-complete.md

@@ -33,7 +33,7 @@ Reflection: "Have I introduced any bugs or regressions?"
 
 1. Reflection: "Does this match what the user asked for?"
 2. Close out all TodoWrite items for this task
-3. Move task to recentlyCompleted in ready.json
+3. **Run `node node_modules/wogiflow/scripts/flow-done.js <taskId>`** — this is the ONLY supported way to complete a task. It runs quality gates, moves the task from `inProgress` → `recentlyCompleted`, writes the gate latch, and fires the task-boundary-restart Phase 1 marker. **Do NOT hand-edit `ready.json` to move the task** — that bypasses the CLI and silently disables: quality-gate verification, gate latch, and the task-boundary session restart. If `flow` is not on PATH in this environment, invoke it as `node node_modules/wogiflow/scripts/flow-done.js <taskId>` directly.
 4. Registry maps auto-updated by `registryUpdate` quality gate (runs `flow registry-manager scan` on all active registries — app-map, function-map, api-map, schema-map, service-map)
 5. If `config.webmcp.enabled` and UI files created: run `node node_modules/wogiflow/scripts/flow-webmcp-generator.js scan`
 6. Commit: `feat: Complete wf-XXXXXXXX - [title]`

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

@@ -432,6 +432,10 @@ Use `/wogi-research "question"` for rigorous verification.
 
 ---
 
+{{> methodology-rules}}
+
+---
+
 ## Generated by CLI Bridge
 
 This file was generated by the Wogi Flow CLI bridge.

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

@@ -0,0 +1,149 @@
+## 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.
+
+---
+
+### Research Before Propose (MANDATORY)
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+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.
+
+**Config**: `hooks.rules.researchEvidenceGate.{enabled,minEvidence}` (defaults: `true`, `2`).
+
+---
+
+### Completion-Claim Honesty Scan
+
+**Rule**: At session-end and on `flow health`, scan `ready.json` entries for two contradiction classes and surface (not block) them for user reconciliation.
+
+- **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.
+
+**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.
+
+**Mode**: surface-and-prompt, non-blocking. A hard-fail at session-end has no recovery path.
+
+**Enforcement**: `scripts/flow-completion-truth-gate.js` → `scanForClaimContradictions()`. Invoked by `flow-session-end.js` and `flow-health.js`.
+
+---
+
+### Merge-Plan Artifact Gate
+
+**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`.
+
+**Mechanical invariant**: count of SHA-prefixed lines in the plan MUST equal `git log <base>..<branch> | wc -l`. Mismatch blocks the merge.
+
+**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`.
+
+**Enforcement**: `scripts/flow-structure-sensor.js`, `.claude/commands/wogi-finalize.md` Step 2.5.
+
+---
+
+### Story Creation Quality Gates
+
+**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).
+
+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.
+
+**Config**: `storyFlow.consumerImpactAnalysis.*`, `storyFlow.scopeConfidenceAudit.*`, `storyFlow.itemReconciliation.*` in `.workflow/config.json`.
+
+---
+
+### Workspace Autonomous-Mode Action-After-Completion Contract
+
+**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:
+
+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.
+
+**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.
+
+**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.
+
+**Config**: `workspace.autoPickupChannelDispatches` (default `true`).
+
+---
+
+### Workspace Worker Cannot Prompt User Directly
+
+**Applies to**: workspace worker mode.
+
+**Rule**: The `AskUserQuestion` tool is mechanically blocked in worker mode. Questions to the user MUST be channel-dispatched to the manager via `## QUESTION: ...`.
+
+**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.
+
+**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`).
+
+---
+
+### Workspace Worker Text-Question Classifier
+
+**Applies to**: workspace worker mode.
+
+**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.
+
+**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.
+
+**Enforcement**: `scripts/flow-worker-question-classifier.js`. Config: `workspace.aiWorkerQuestionClassifier.{enabled,minConfidence,model}`.
+
+---
+
+### Workspace Worker Silent-Halt Detection
+
+**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.
+
+**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.
+
+**Deadline**: default `expectedDurationMs` = 30 min. Callers override per-dispatch for long tasks.
+
+**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`
+
+---
+
+### Code Quality Patterns (generic)
+
+These apply to any codebase being built with WogiFlow's help.
+
+**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.
+
+**2. Named Constants for Magic Numbers** — define thresholds and limits as named constants; don't inline literals.
+
+```js
+const COVERAGE_THRESHOLDS = { default: 0.7, comprehensive: 0.85, concise: 0.5 };
+```
+
+Self-documenting; easier to maintain.

package/lib/workspace-routing.js

@@ -710,6 +710,50 @@ async function dispatchToChannel(workspaceRoot, repoName, taskId, opts = {}) {
     return { ok: false, message: `Invalid task ID format: "${taskId}" — expected wf-XXXXXXXX` };
   }
 
+  // Research-before-propose gate (manager mode): require evidence that the
+  // manager has read at least N state/spec files before dispatching work.
+  //
+  // Architectural note (ARCH-005): the dispatch gate is wired here in the
+  // routing layer rather than via pre-tool-orchestrator because channel
+  // dispatch is a lib-level operation that can be invoked outside the
+  // Claude Code PreToolUse hook path (e.g., by a worker's internal CLI
+  // or by a script). Wiring here ensures the gate fires on every dispatch,
+  // regardless of invocation surface. The spec-write gate is wired in the
+  // orchestrator because Edit/Write is hook-surface-only.
+  //
+  // Error handling (CL-005): separate catches so gate-not-installed (the
+  // intended fail-open path) is distinct from config-load failures (which
+  // indicate broken installs worth surfacing in DEBUG) and from gate
+  // runtime errors (which suggest a bug in the gate itself).
+  let dispatchGateModule = null;
+  try {
+    dispatchGateModule = require('../scripts/hooks/core/research-evidence-gate');
+  } catch (_err) {
+    // Gate module not installed — fail-open silently; this is expected on
+    // older installs that predate the research-evidence gate.
+  }
+  if (dispatchGateModule) {
+    let cfg = null;
+    try {
+      const { getConfig } = require('../scripts/flow-utils');
+      cfg = getConfig();
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[dispatchToChannel] Config load failed (gate still enforced with defaults): ${err.message}`);
+      }
+    }
+    try {
+      const dispatchGate = dispatchGateModule.checkDispatchEvidenceGate(cfg);
+      if (dispatchGate.blocked) {
+        return { ok: false, message: dispatchGate.message };
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[dispatchToChannel] Dispatch gate runtime error (fail-open): ${err.message}`);
+      }
+    }
+  }
+
   const configPath = path.join(workspaceRoot, 'wogi-workspace.json');
   const config = safeReadJson(configPath);
   if (!config || typeof config !== 'object') {

package/package.json

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

package/scripts/flow-config-defaults.js

@@ -986,7 +986,8 @@ const CONFIG_DEFAULTS = {
         configChange: { enabled: false },
         setup: { enabled: true, autoOnboard: false, maintenanceTasks: ['healthCheck', 'cleanupLocks'] },
         sessionCleanup: { enabled: true },
-        phaseGate: { enabled: true }
+        phaseGate: { enabled: true },
+        researchEvidenceGate: { enabled: true, minEvidence: 2 }
       }
     },
     claudeCode: { installPath: '.claude/settings.local.json' }
@@ -1066,6 +1067,14 @@ const CONFIG_DEFAULTS = {
   // --- Decisions ---
   decisions: { amendmentTracking: { enabled: false } },
 
+  // --- Session End ---
+  // autoPushInWorker: when /wogi-session-end runs inside a workspace worker
+  // (WOGI_WORKSPACE_ROOT set, WOGI_REPO_NAME !== 'manager'), the worker must
+  // not prompt the user directly. true (default) → auto-push silently.
+  // false → skip push entirely; user pushes manually. Non-worker sessions
+  // are unaffected and still see the interactive prompt.
+  sessionEnd: { autoPushInWorker: true },
+
   // --- Community ---
   community: {
     enabled: false,

package/scripts/flow-session-end.js

@@ -41,6 +41,17 @@ const { getReadyData, saveReadyData } = require('./flow-utils');
 // v2.6.1: Use centralized state cleanup module
 const { cleanupStaleState } = require('./flow-state-cleanup');
 
+// Workspace worker detection — used by offerPush() to branch between
+// interactive prompt (single-repo) and silent auto-push (worker mode).
+// Loaded eagerly; if module is missing on a broken install, fail loud
+// rather than masking the issue via a lazy require deep in offerPush().
+let isWorker;
+try {
+  isWorker = require('../lib/workspace-worker-ready').isWorker;
+} catch (_err) {
+  isWorker = () => false;
+}
+
 // v1.8.0 automatic memory management
 let memoryDb = null;
 try {
@@ -448,22 +459,63 @@ function analyzeCrossSessionPatterns() {
 }
 
 /**
- * Offer to push to remote
+ * Offer to push to remote.
+ *
+ * In workspace worker mode (WOGI_WORKSPACE_ROOT + WOGI_REPO_NAME !== 'manager'),
+ * workers must not prompt the user directly — that violates the Workspace Worker
+ * Cannot Prompt User Directly contract (decisions.md v2.20.1+). Instead:
+ *   - config.sessionEnd.autoPushInWorker === true  (default) → push silently
+ *   - config.sessionEnd.autoPushInWorker === false          → skip push silently
+ * In single-repo mode (the common case), the interactive prompt is unchanged.
  */
 async function offerPush() {
   if (!isGitRepo()) return;
 
   try {
     execSync('git remote get-url origin', { stdio: 'pipe' });
+  } catch (_err) {
+    return;
+  }
 
-    const confirm = await prompt('Push to remote? (y/N) ');
+  // Worker-mode detection + secondary validation (SEC-001). isWorker() checks
+  // WOGI_WORKSPACE_ROOT + WOGI_REPO_NAME env vars. For defense in depth,
+  // confirm that `.workspace/` exists inside WOGI_WORKSPACE_ROOT before
+  // treating env-var signals as authoritative — this narrows the window in
+  // which a misconfigured single-repo session could be misidentified as a
+  // worker and auto-push without confirmation.
+  if (isWorker() && isValidWorkspaceRoot()) {
+    const autoPush = getConfigValue('sessionEnd.autoPushInWorker', true);
+    if (!autoPush) {
+      console.log(color('dim', '⊘ Push skipped (worker mode — autoPushInWorker: false)'));
+      return;
+    }
+    try {
+      execSync('git push', { stdio: 'inherit' });
+      success('Auto-pushed (worker mode)');
+    } catch (err) {
+      warn(`Auto-push failed: ${err.message}`);
+    }
+    return;
+  }
 
+  try {
+    const confirm = await prompt('Push to remote? (y/N) ');
     if (confirm.toLowerCase() === 'y') {
       execSync('git push', { stdio: 'inherit' });
       success('Pushed to remote');
     }
   } catch (_err) {
-    // No remote configured, skip
+    // Prompt or push failed, skip
+  }
+}
+
+function isValidWorkspaceRoot() {
+  const root = process.env.WOGI_WORKSPACE_ROOT;
+  if (!root || !path.isAbsolute(root)) return false;
+  try {
+    return fs.existsSync(path.join(root, '.workspace'));
+  } catch (_err) {
+    return false;
   }
 }
 

package/scripts/hooks/core/phase-gate.js

@@ -164,6 +164,28 @@ function transitionPhase(from, to, taskId) {
     return false;
   }
 
+  // Research-evidence gate: transitions into proposal phases (spec_review,
+  // coding) require minimum evidence fingerprint. Fail-open if gate module
+  // is absent. Prints the block message to stderr so flow-phase.js CLI
+  // surfaces it to the AI invoking the transition.
+  if (to === 'spec_review' || to === 'coding') {
+    try {
+      const { checkPhaseTransitionEvidence } = require('./research-evidence-gate');
+      let cfg = null;
+      try {
+        const { getConfig } = require('../../flow-utils');
+        cfg = getConfig();
+      } catch (_err) { /* fail-open on config error */ }
+      const result = checkPhaseTransitionEvidence(from, to, cfg);
+      if (result.blocked) {
+        console.error(result.message);
+        return false;
+      }
+    } catch (_err) {
+      // Gate not installed — fail-open
+    }
+  }
+
   return writePhaseState({
     phase: to,
     taskId: taskId || current.taskId,

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

@@ -167,6 +167,21 @@ function handlePostCompact() {
     }
   }
 
+  // Clear research-evidence fingerprint after compaction — the AI has fresh
+  // context, so claims of "already read X" in the previous context no longer
+  // apply. The gate must force re-reading in the new context.
+  try {
+    const { clearResearchEvidence } = require('./research-evidence-gate');
+    clearResearchEvidence();
+    if (process.env.DEBUG) {
+      console.error('[post-compact] Research-evidence cleared');
+    }
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[post-compact] Research-evidence clear failed: ${err.message}`);
+    }
+  }
+
   // 3. Re-set routing-pending flag
   // After compaction, the AI has fresh context and may try to act without routing.
   // Setting routing-pending ensures the next tool use goes through routing checks.

package/scripts/hooks/core/pre-tool-orchestrator.js

@@ -80,6 +80,9 @@ function runPreToolGates(ctx, deps) {
   // Phase-read recording (side effect)
   if (toolName === 'Read' && filePath) {
     try { deps.recordPhaseRead(filePath); } catch (_err) { /* fail-open */ }
+    if (deps.recordEvidenceRead) {
+      try { deps.recordEvidenceRead(filePath); } catch (_err) { /* fail-open */ }
+    }
   }
 
   // Phase gate
@@ -114,6 +117,24 @@ function runPreToolGates(ctx, deps) {
     }
   }
 
+  // Research-evidence gate (spec-write): blocks Edit/Write to proposal paths
+  // when the AI has not read enough evidence files this task turn.
+  if ((toolName === 'Edit' || toolName === 'Write') && deps.checkSpecWriteGate) {
+    try {
+      const specResult = deps.checkSpecWriteGate(filePath, config);
+      if (specResult.blocked) {
+        return {
+          allowed: false,
+          blocked: true,
+          reason: 'Research-evidence gate: insufficient research before proposal',
+          message: specResult.message,
+        };
+      }
+    } catch (_err) {
+      if (process.env.DEBUG) console.error(`[Hook] Research-evidence gate error (fail-open): ${_err.message}`);
+    }
+  }
+
   // Scope gate (Edit/Write only)
   if (toolName === 'Edit' || toolName === 'Write') {
     coreResult = deps.checkScopeGate({ filePath, operation: toolName.toLowerCase() }, config);
@@ -133,6 +154,9 @@ function runPreToolGates(ctx, deps) {
     if (typeof skillName === 'string' && /^wogi-(bulk|start)$/i.test(skillName)) {
       deps.markSkillPending(skillName.toLowerCase(), { args: toolInput.args });
       try { deps.clearPhaseReads(); } catch (_err) { /* fail-open */ }
+      if (deps.clearResearchEvidence) {
+        try { deps.clearResearchEvidence(); } catch (_err) { /* fail-open */ }
+      }
       if (process.env.DEBUG) {
         console.error(`[Hook] Marked skill ${skillName} as pending (via Skill tool)`);
       }

package/scripts/hooks/core/research-evidence-gate.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow - Research-Evidence Gate (Core Module)
+ *
+ * Enforces the "Research Before Propose" methodology rule by tracking which
+ * state/spec/epic files the AI has Read in the current task turn, and blocking
+ * proposal actions (spec writes, channel-dispatch to workers) until a minimum
+ * evidence threshold has been reached.
+ *
+ * Does NOT block AskUserQuestion, plain Read/Glob/Grep/WebSearch, conversational
+ * text, or non-proposal edits. Asking the user is a valid escape hatch.
+ *
+ * State file: .workflow/state/research-evidence.json
+ * Fail-open: If state file is missing/corrupt or config disabled, allow the tool call.
+ *
+ * Three entry points:
+ *   recordEvidenceRead(filePath)         — called when Read targets an evidence file
+ *   checkSpecWriteGate(filePath, config) — called before Edit/Write to proposal paths
+ *   checkDispatchEvidenceGate(config)    — called before manager channel-dispatch
+ *   clearResearchEvidence()              — called on new task start / session end / post-compact
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { PATHS, safeJsonParse } = require('../../flow-utils');
+
+const EVIDENCE_FILE = path.join(PATHS.state, 'research-evidence.json');
+
+// Relative-to-project path prefixes that count as evidence when Read.
+// Any file whose project-relative path starts with one of these prefixes
+// increments the evidence counter.
+const EVIDENCE_PREFIXES = [
+  '.workflow/state/',
+  '.workflow/changes/',
+  '.workflow/specs/',
+  '.workflow/epics/'
+];
+
+// Path prefixes that trigger the spec-write gate when targeted by Edit/Write.
+// Writing to these paths = "proposing a spec" = must have evidence first.
+const PROPOSAL_PREFIXES = [
+  '.workflow/changes/',
+  '.workflow/specs/',
+  '.workflow/epics/'
+];
+
+// Default threshold: minimum number of distinct evidence-file reads required
+// before a proposal action is allowed. Can be overridden by config.
+const DEFAULT_MIN_EVIDENCE = 2;
+
+function toProjectRelative(filePath) {
+  try {
+    // Canonicalize both sides via realpath to prevent symlink escape
+    // (SEC-003): a symlink in PATHS.root or the input path could make a
+    // file outside the project appear inside after a plain path.relative.
+    let rootCanon = PATHS.root;
+    let targetCanon = path.resolve(filePath);
+    try { rootCanon = fs.realpathSync(PATHS.root); } catch (_err) { /* root may not exist mid-test */ }
+    try { targetCanon = fs.realpathSync(targetCanon); } catch (_err) { /* target may not exist yet */ }
+    const rel = path.relative(rootCanon, targetCanon);
+    return rel.split(path.sep).join('/');
+  } catch (_err) {
+    return null;
+  }
+}
+
+function matchesPrefix(relPath, prefixes) {
+  if (!relPath || relPath.startsWith('..')) return false;
+  return prefixes.some(p => relPath.startsWith(p));
+}
+
+/**
+ * Record that an evidence file was read. Called from PreToolUse on Read.
+ * De-duplicates: reading the same file twice still counts as 1.
+ *
+ * Write strategy (CL-001): atomic temp-file + rename. A concurrent tool call
+ * that loses the read-modify-write race will at worst lose one evidence entry,
+ * which causes a false-block that the user resolves by reading one more file.
+ * The atomic rename prevents partial writes on crash.
+ */
+function recordEvidenceRead(filePath) {
+  if (!filePath || typeof filePath !== 'string') return;
+
+  const rel = toProjectRelative(filePath);
+  if (!matchesPrefix(rel, EVIDENCE_PREFIXES)) return;
+
+  try {
+    const existing = safeJsonParse(EVIDENCE_FILE, {});
+    if (!existing.reads || typeof existing.reads !== 'object') existing.reads = {};
+    if (!existing.reads[rel]) {
+      existing.reads[rel] = { at: new Date().toISOString() };
+      const tmp = `${EVIDENCE_FILE}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(existing, null, 2));
+      fs.renameSync(tmp, EVIDENCE_FILE);
+      if (process.env.DEBUG) {
+        console.error(`[ResearchEvidenceGate] Recorded evidence read: ${rel}`);
+      }
+    }
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[ResearchEvidenceGate] Failed to record read: ${err.message}`);
+    }
+  }
+}
+
+function getEvidenceCount() {
+  try {
+    const data = safeJsonParse(EVIDENCE_FILE, {});
+    if (!data.reads || typeof data.reads !== 'object') return 0;
+    return Object.keys(data.reads).length;
+  } catch (_err) {
+    return 0;
+  }
+}
+
+function isGateEnabled(config) {
+  const gateCfg = config?.hooks?.rules?.researchEvidenceGate;
+  if (gateCfg === undefined || gateCfg === null) return true;
+  if (gateCfg === false) return false;
+  if (typeof gateCfg === 'object' && gateCfg.enabled === false) return false;
+  return true;
+}
+
+function getMinEvidence(config) {
+  const v = config?.hooks?.rules?.researchEvidenceGate?.minEvidence;
+  if (typeof v === 'number' && v >= 0 && Number.isFinite(v)) return v;
+  return DEFAULT_MIN_EVIDENCE;
+}
+
+/**
+ * Block Edit/Write to a proposal path when evidence fingerprint is below threshold.
+ * Called from pre-tool-orchestrator before Edit/Write runs.
+ *
+ * @param {string} filePath - Path being written/edited
+ * @param {Object} config
+ * @returns {{ blocked: boolean, message?: string }}
+ */
+function checkSpecWriteGate(filePath, config) {
+  try {
+    if (!isGateEnabled(config)) return { blocked: false };
+    if (!filePath || typeof filePath !== 'string') return { blocked: false };
+
+    const rel = toProjectRelative(filePath);
+    if (!matchesPrefix(rel, PROPOSAL_PREFIXES)) return { blocked: false };
+
+    const minEvidence = getMinEvidence(config);
+    const count = getEvidenceCount();
+    if (count >= minEvidence) return { blocked: false };
+
+    return {
+      blocked: true,
+      message:
+        `Research-before-propose: this writes a spec/change/epic (${rel}), but you have only ` +
+        `read ${count} evidence file(s) this task turn. Minimum required: ${minEvidence}.\n\n` +
+        `Before proposing, read relevant files from:\n` +
+        `  .workflow/state/decisions.md, feedback-patterns.md, app-map.md, function-map.md, api-map.md\n` +
+        `  the task spec (.workflow/changes/<taskId>.md or .workflow/specs/<id>.md)\n` +
+        `  .workflow/epics/ if this task belongs to an epic\n\n` +
+        `If you genuinely need clarification before proposing, use AskUserQuestion — that is allowed.\n` +
+        `The rule is "don't propose before researching," not "never ask."`
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[ResearchEvidenceGate] Spec-write gate error (fail-open): ${err.message}`);
+    }
+    return { blocked: false };
+  }
+}
+
+/**
+ * Block channel-dispatch to a worker when the manager has no evidence of
+ * having researched the target's state. Called from lib/workspace-routing.js
+ * before dispatchToChannel posts.
+ *
+ * @param {Object} config
+ * @returns {{ blocked: boolean, message?: string }}
+ */
+function checkDispatchEvidenceGate(config) {
+  try {
+    if (!isGateEnabled(config)) return { blocked: false };
+
+    // Manager-mode only: workers don't dispatch. Single-repo sessions
+    // (no WOGI_WORKSPACE_ROOT) are n/a — there are no workers to dispatch
+    // to, so the evidence requirement does not apply (CL-003).
+    const workspaceRoot = process.env.WOGI_WORKSPACE_ROOT;
+    const repo = process.env.WOGI_REPO_NAME;
+    const isManager = !!workspaceRoot && (!repo || repo === 'manager');
+    if (!isManager) return { blocked: false };
+
+    const minEvidence = getMinEvidence(config);
+    const count = getEvidenceCount();
+    if (count >= minEvidence) return { blocked: false };
+
+    return {
+      blocked: true,
+      message:
+        `Research-before-dispatch: dispatching to a worker proposes work, but the manager has only ` +
+        `read ${count} evidence file(s) this turn. Minimum required: ${minEvidence}.\n\n` +
+        `Before dispatching, read relevant state from the target member repo:\n` +
+        `  <member-repo>/.workflow/state/decisions.md, app-map.md, feedback-patterns.md\n` +
+        `  <member-repo>/.workflow/changes/ for existing task specs\n\n` +
+        `Silent workers that receive poorly-specified work cost the most to recover. ` +
+        `The Wogi Hub manager incident that prompted this rule dispatched Employee-class ` +
+        `clarifying-question work without reading the existing class system.`
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[ResearchEvidenceGate] Dispatch gate error (fail-open): ${err.message}`);
+    }
+    return { blocked: false };
+  }
+}
+
+/**
+ * Block phase transitions into proposal phases (spec_review, coding) when
+ * the AI has not read enough evidence files this task turn. Called from
+ * phase-gate.js transitionPhase() when the target is a proposal phase.
+ *
+ * @param {string} from
+ * @param {string} to
+ * @param {Object} config
+ * @returns {{ blocked: boolean, message?: string }}
+ */
+function checkPhaseTransitionEvidence(from, to, config) {
+  try {
+    if (!isGateEnabled(config)) return { blocked: false };
+    if (to !== 'spec_review' && to !== 'coding') return { blocked: false };
+
+    const minEvidence = getMinEvidence(config);
+    const count = getEvidenceCount();
+    if (count >= minEvidence) return { blocked: false };
+
+    return {
+      blocked: true,
+      message:
+        `Research-before-propose: transitioning to "${to}" requires ${minEvidence} evidence ` +
+        `file read(s) this task turn; you have ${count}.\n\n` +
+        `Before transitioning to a proposal phase, read relevant files from:\n` +
+        `  .workflow/state/decisions.md, feedback-patterns.md, app-map.md, function-map.md\n` +
+        `  the task spec (.workflow/changes/<taskId>.md or .workflow/specs/<id>.md)\n` +
+        `  .workflow/epics/ if this task belongs to an epic\n\n` +
+        `AskUserQuestion is not blocked — ask if clarification is genuinely needed.`
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[ResearchEvidenceGate] Phase-transition gate error (fail-open): ${err.message}`);
+    }
+    return { blocked: false };
+  }
+}
+
+/**
+ * Clear evidence state. Called at:
+ *   - New task start (pre-tool-use.js Skill hook for wogi-start)
+ *   - Session end
+ *   - Post-compact (forces re-read in new context)
+ */
+function clearResearchEvidence() {
+  try {
+    fs.writeFileSync(EVIDENCE_FILE, JSON.stringify({ reads: {} }, null, 2));
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`[ResearchEvidenceGate] Failed to clear evidence: ${err.message}`);
+    }
+  }
+}
+
+module.exports = {
+  recordEvidenceRead,
+  checkSpecWriteGate,
+  checkDispatchEvidenceGate,
+  checkPhaseTransitionEvidence,
+  clearResearchEvidence,
+  getEvidenceCount,
+  EVIDENCE_FILE,
+  EVIDENCE_PREFIXES,
+  PROPOSAL_PREFIXES,
+  DEFAULT_MIN_EVIDENCE
+};

package/scripts/hooks/core/session-end.js

@@ -110,6 +110,13 @@ function handleSessionEnd(input) {
       // Non-critical — phase-read gate may not be installed
     }
 
+    try {
+      const { clearResearchEvidence } = require('./research-evidence-gate');
+      clearResearchEvidence();
+    } catch (_err) {
+      // Non-critical — research-evidence gate may not be installed
+    }
+
     // State folder hygiene — clean stale/orphan files (fire-and-forget)
     try {
       const hygiene = cleanStaleFiles();

package/scripts/hooks/core/task-boundary-reset.js

@@ -50,6 +50,12 @@ const { getConfig, PATHS } = require('../../flow-utils');
 const { safeJsonParse } = require('../../flow-io');
 
 const PENDING_MARKER_FILE = 'task-just-completed';
+const LAST_TRIGGERED_FILE = 'task-boundary-last-triggered';
+// Window during which a recentlyCompleted[0] entry is considered "fresh
+// enough" to retro-mark Phase 1 from the Stop hook. Large enough to cover
+// a slow quality-gate run; small enough that a session opened hours later
+// doesn't trigger a bogus restart.
+const FRESHNESS_WINDOW_MS = 5 * 60 * 1000;
 
 /**
  * Locate the pending-marker file path inside .workflow/state/.
@@ -59,6 +65,26 @@ function getPendingMarkerPath() {
   return path.join(PATHS.state, PENDING_MARKER_FILE);
 }
 
+function getLastTriggeredPath() {
+  return path.join(PATHS.state, LAST_TRIGGERED_FILE);
+}
+
+function readLastTriggered() {
+  try {
+    return safeJsonParse(getLastTriggeredPath(), null);
+  } catch (_err) {
+    return null;
+  }
+}
+
+function writeLastTriggered(taskId) {
+  try {
+    const p = getLastTriggeredPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ taskId, at: new Date().toISOString() }));
+  } catch (_err) { /* best effort — anti-replay is defense-in-depth */ }
+}
+
 /**
  * Phase 1 — mark that a task just completed and a restart is desired at the
  * next Stop-hook boundary. Safe to call even when the feature is disabled;
@@ -196,6 +222,13 @@ function consumeAndTriggerRestart() {
     return { triggered: false, reason: `sigterm-failed: ${err.message}` };
   }
 
+  // Record anti-replay sentinel so the Stop-hook fallback in the NEW session
+  // (post-restart) doesn't retro-mark the same recentlyCompleted[0] and
+  // trigger a second restart.
+  if (markerPayload?.taskId) {
+    writeLastTriggered(markerPayload.taskId);
+  }
+
   return {
     triggered: true,
     flagPath: pre.flagPath,
@@ -203,6 +236,72 @@ function consumeAndTriggerRestart() {
   };
 }
 
+/**
+ * Phase 1 fallback — called from the Stop hook BEFORE
+ * consumeAndTriggerRestart. Detects a freshly-completed task in
+ * recentlyCompleted and writes the pending marker if neither of the primary
+ * Phase 1 paths fired.
+ *
+ * Why this exists: the primary Phase 1 writers are (a) flow-done.js:604 when
+ * `flow done <taskId>` runs, and (b) task-completed.js:522 driven by Claude
+ * Code's TaskCompleted hook. Path (b) does not fire for /wogi-start workflow
+ * completions (TaskCompleted fires for Task-tool sub-agents only — the reason
+ * for the two-phase redesign above). Path (a) only fires if the agent runs
+ * `flow done`. Older phase docs quietly encouraged "move task to
+ * recentlyCompleted in ready.json" as a substitute for `flow done`, which
+ * silently disables the restart. This fallback catches that case: if a fresh
+ * completion is visible in ready.json but no marker exists, we write one so
+ * Phase 2 can do its job.
+ *
+ * Anti-replay: recentlyCompleted[0] survives the SIGTERM + wrapper restart
+ * cycle, so without a guard the Stop hook in the NEW session would see the
+ * same fresh completion and trigger a second restart. The
+ * task-boundary-last-triggered sentinel prevents that — it records the last
+ * taskId we triggered on, and we skip if the current fresh completion
+ * matches.
+ *
+ * @returns {{ marked: boolean, taskId?: string, reason?: string }}
+ */
+function ensurePhase1MarkedIfRecentlyCompleted() {
+  try {
+    if (hasPendingMarker()) {
+      return { marked: false, reason: 'marker-already-present' };
+    }
+
+    const readyPath = path.join(PATHS.state, 'ready.json');
+    const ready = safeJsonParse(readyPath, null);
+    const recent = ready && Array.isArray(ready.recentlyCompleted)
+      ? ready.recentlyCompleted[0]
+      : null;
+    if (!recent || typeof recent !== 'object' || !recent.id || !recent.completedAt) {
+      return { marked: false, reason: 'no-fresh-completion' };
+    }
+
+    const completedTs = new Date(recent.completedAt).getTime();
+    if (!Number.isFinite(completedTs)) {
+      return { marked: false, reason: 'unparseable-completedAt' };
+    }
+    const ageMs = Date.now() - completedTs;
+    if (ageMs < 0 || ageMs > FRESHNESS_WINDOW_MS) {
+      return { marked: false, reason: 'stale-completion' };
+    }
+
+    const lastTriggered = readLastTriggered();
+    if (lastTriggered?.taskId === recent.id) {
+      return { marked: false, reason: 'already-triggered-for-this-task' };
+    }
+
+    const result = markRestartPending({
+      taskId: recent.id,
+      taskTitle: recent.title,
+      source: 'stop-hook-fallback'
+    });
+    return { marked: result.marked, taskId: recent.id, reason: result.reason };
+  } catch (err) {
+    return { marked: false, reason: `fallback-error: ${err.message}` };
+  }
+}
+
 /**
  * Convenience: whether a pending marker currently exists. Diagnostic only.
  * @returns {boolean}
@@ -219,6 +318,10 @@ module.exports = {
   // Phase 1 — called from task-completion code paths
   markRestartPending,
 
+  // Phase 1 fallback — called from the Stop hook entry BEFORE Phase 2,
+  // catches the case where flow-done didn't run and TaskCompleted didn't fire
+  ensurePhase1MarkedIfRecentlyCompleted,
+
   // Phase 2 — called from the Stop hook entry
   consumeAndTriggerRestart,
 

package/scripts/hooks/entry/claude-code/pre-tool-use.js

@@ -35,6 +35,20 @@ try {
   clearPhaseReads = prg.clearPhaseReads;
 } catch (_err) { if (process.env.DEBUG) console.error(`[Hook] Phase-read gate not loaded: ${_err.message}`); }
 
+let recordEvidenceRead = () => {}, checkSpecWriteGate = () => ({ blocked: false }), clearResearchEvidence = () => {};
+try {
+  const reg = require('../../core/research-evidence-gate');
+  recordEvidenceRead = reg.recordEvidenceRead;
+  checkSpecWriteGate = reg.checkSpecWriteGate;
+  clearResearchEvidence = reg.clearResearchEvidence;
+} catch (err) {
+  // CL-004: load failure for a gate file that SHOULD be present is a
+  // deployment issue worth surfacing even without DEBUG set. Silently
+  // shimming masks broken installs. Preserve fail-open (shims above)
+  // so the hook pipeline still works, but log to stderr so operators see it.
+  console.error(`[Hook] WARNING: Research-evidence gate failed to load — gate is disabled. ${err.message}`);
+}
+
 const _noop = () => ({ allowed: true, blocked: false });
 let checkDeployGate = _noop, checkWriteBlock = _noop;
 try { const dg = require('../../core/deploy-gate'); checkDeployGate = dg.checkDeployGate; checkWriteBlock = dg.checkWriteBlock; } catch (_err) { if (process.env.DEBUG) console.error(`[Hook] Deploy gate not loaded: ${_err.message}`); }
@@ -84,6 +98,7 @@ runHook('PreToolUse', async ({ input, parsedInput }) => {
     checkRoutingGate, clearRoutingPending, hasActiveTask,
     checkPhaseGate, checkCommitLogGate,
     recordPhaseRead, checkPhaseReadGate, clearPhaseReads,
+    recordEvidenceRead, checkSpecWriteGate, clearResearchEvidence,
     checkDeployGate, checkWriteBlock,
     checkStrikeGate, checkBugfixScope, checkScopeMutation,
     checkGitSafety, checkManagerBoundary, checkWorkerBoundary,

package/scripts/hooks/entry/claude-code/stop.js

@@ -155,7 +155,33 @@ runHook('Stop', async ({ parsedInput }) => {
   // No-op unless task-just-completed marker exists AND feature is enabled
   // AND wogi-claude wrapper env is present.
   try {
-    const { consumeAndTriggerRestart, hasPendingMarker } = require('../../core/task-boundary-reset');
+    const {
+      consumeAndTriggerRestart,
+      hasPendingMarker,
+      ensurePhase1MarkedIfRecentlyCompleted
+    } = require('../../core/task-boundary-reset');
+
+    // Phase 1 fallback: if the task completed via a path that didn't write the
+    // marker (e.g., agent edited ready.json directly instead of running
+    // `flow done`, or TaskCompleted hook didn't fire), retro-mark here so
+    // Phase 2 below can consume it. Anti-replay sentinel prevents double-firing
+    // across the SIGTERM + wrapper restart cycle.
+    try {
+      const fallback = ensurePhase1MarkedIfRecentlyCompleted();
+      if (fallback.marked && process.env.DEBUG) {
+        console.error(`[Stop] Phase 1 fallback marked ${fallback.taskId}`);
+      } else if (!fallback.marked && fallback.reason !== 'marker-already-present' &&
+                 fallback.reason !== 'no-fresh-completion' &&
+                 fallback.reason !== 'stale-completion' &&
+                 fallback.reason !== 'already-triggered-for-this-task' &&
+                 process.env.DEBUG) {
+        console.error(`[Stop] Phase 1 fallback skipped: ${fallback.reason}`);
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`[Stop] Phase 1 fallback error (fail-open): ${err.message}`);
+      }
+    }
 
     // If we're about to restart, record the session in history FIRST so the
     // new session can find the prior session's resume token. Use parsedInput

package/.workflow/state/bugfix-scope.json.template

@@ -1,7 +0,0 @@
-{
-  "taskId": null,
-  "uniqueFiles": [],
-  "thresholdReached": false,
-  "scopeInventory": null,
-  "warnedAt": null
-}

package/.workflow/state/deploy-history.json.template

@@ -1,3 +0,0 @@
-{
-  "deploys": []
-}

package/.workflow/state/deploy-routes.json.template

@@ -1,4 +0,0 @@
-{
-  "routes": [],
-  "lastUpdated": null
-}

package/.workflow/state/strike-tracker.json.template

@@ -1,3 +0,0 @@
-{
-  "tasks": {}
-}