wogiflow 2.29.9 → 2.30.0

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

@@ -105,6 +105,34 @@ Options:
 
 Use `AskUserQuestion` to present these options.
 
+### Step 2.5: Mechanical-Enforcement Check (wf-037f8d66)
+
+**Rules without mechanical enforcement are vibes.** Before writing any new rule, classify how it will be enforced:
+
+| Enforcement type | Examples | Reliability |
+|---|---|---|
+| **Mechanical gate** (PreToolUse/Stop hook, type system, lint rule, standards-checker pattern) | deferral-gate, research-evidence-gate, phase-read-gate, hook-three-layer LOC check, forbidden-patterns | High — agent cannot skip |
+| **Test assertion** (unit/integration test that fails on violation) | architectural test asserting no hardcoded paths | High — fails CI |
+| **Schema constraint** (config schema, JSON schema, Go type) | required fields, enum values | High — fails parse/compile |
+| **Vibes-only** (rule text in CLAUDE.md, decisions.md, or rule file with no mechanical check) | "use kebab-case", "prefer composition over inheritance", "always X / never Y" | **Low — agent skips it** |
+
+**The rule must declare its enforcement type.** If "vibes-only," call it out explicitly:
+
+> ⚠ This rule has no mechanical gate. It will be inconsistently enforced. To make it stick, propose one of:
+> - A standards-checker pattern in `.workflow/state/forbidden-patterns.json`
+> - A new gate in `scripts/hooks/core/`
+> - A unit test in `tests/`
+> - A type-system constraint
+>
+> Without one of those, expect the same class of violation to recur.
+
+**Anti-rationalization**:
+- "I'll just trust the AI to follow it" → WRONG. The reason this rule exists is the AI didn't follow it last time.
+- "It's documented in CLAUDE.md" → Documentation ≠ enforcement. Both can coexist.
+- "We can add the gate later" → "Later" is "never" for vibes-rules. Either commit to a gate now, or accept inconsistent enforcement.
+
+If user accepts vibes-only, proceed with the rule but tag it `enforcementType: "vibes-only"` in decisions.md so future audits surface it.
+
 ### Step 3: Assess Clarity
 
 Evaluate if the rule needs clarification. **Skip questions if the rule is already clear and specific.**

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

@@ -174,6 +174,7 @@ Given a pattern to promote:
    - Correction examples → Verification criteria
 
 3. **Delegate duplicate checking to `/wogi-decide --from-pattern`** which handles duplicate detection and the full rule-writing flow. This ensures a single source of truth for all rule-creation logic.
+   - **Note (wf-037f8d66)**: `/wogi-decide` Step 2.5 will require declaring the rule's enforcement type (mechanical gate / test / schema constraint / vibes-only). Patterns being promoted to rules MUST answer "what's the gate?" — if no mechanical enforcement exists, the rule is vibes-only and will not reliably enforce. The fact that this pattern recurred enough to be promoted is itself evidence that vibes-only didn't work.
 
 4. **Ask user for any additions:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wogiflow",
-  "version": "2.29.9",
+  "version": "2.30.0",
   "description": "AI-powered development workflow management system with multi-model support",
   "main": "lib/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "flow": "./scripts/flow",
-    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-audit-gates.test.js tests/flow-standards-hook-three-layer.test.js tests/flow-correction-detector-reconcile.test.js tests/flow-correction-backfill.test.js tests/flow-audit-gates-feature-output-health.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/workspace-ipc-sqlite.test.js tests/workspace-ipc-multi-worker.test.js tests/flow-story-gates.test.js tests/flow-workspace-restart-handoff.test.js tests/flow-wogi-claude-wrapper.test.js tests/flow-wave1-integrations.test.js tests/flow-wave2-integrations.test.js tests/flow-wave3-integrations.test.js tests/flow-commit-claims-gate.test.js tests/auto-review.test.js tests/gate-telemetry-surface.test.js tests/agents-md-alias.test.js tests/flow-skill-manage.test.js tests/fuzzy-patch.test.js tests/mode-schema.test.js tests/flow-feature-dossier.test.js tests/flow-autonomous-mode.test.js tests/flow-epic-cascade.test.js tests/flow-workspace-summary.test.js tests/flow-hooks-research-evidence-gate.test.js tests/flow-worker-mcp-strip.test.js tests/flow-orchestrate-corrections.test.js tests/flow-source-fidelity.test.js tests/flow-hooks-long-input-enforcement.test.js tests/workspace-channel-tracking.test.js tests/flow-hooks-deletion-log.test.js tests/flow-task-boundary-reset.test.js tests/flow-deferral-gate.test.js tests/flow-research-required-gate.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
+    "test": "NODE_ENV=test node --test tests/auto-compact-prompt.test.js tests/flow-paths.test.js tests/flow-io.test.js tests/flow-audit-gates.test.js tests/flow-standards-hook-three-layer.test.js tests/flow-correction-detector-reconcile.test.js tests/flow-correction-backfill.test.js tests/flow-audit-gates-feature-output-health.test.js tests/flow-config-loader.test.js tests/flow-damage-control.test.js tests/flow-output.test.js tests/flow-constants.test.js tests/flow-session-state.test.js tests/flow-hooks-integration.test.js tests/flow-utils.test.js tests/flow-security.test.js tests/flow-memory-db.test.js tests/flow-durable-session.test.js tests/flow-skill-matcher.test.js tests/flow-bridge.test.js tests/flow-proactive-compact.test.js tests/flow-cascade-completion.test.js tests/flow-capture-gate.test.js tests/flow-correction-detector-hybrid.test.js tests/flow-promote.test.js tests/flow-archive-runs.test.js tests/flow-memory.test.js tests/flow-hooks-pre-tool-helpers.test.js tests/flow-hooks-bugfix-scope-gate.test.js tests/flow-hooks-routing-gate.test.js tests/flow-hooks-phase-read-gate.test.js tests/flow-hooks-commit-log-gate.test.js tests/flow-hooks-deploy-gate.test.js tests/flow-hooks-todowrite-gate.test.js tests/flow-hooks-git-safety-gate.test.js tests/flow-hooks-scope-mutation-gate.test.js tests/flow-hooks-strike-gate.test.js tests/flow-hooks-component-check.test.js tests/flow-hooks-scope-gate.test.js tests/flow-hooks-implementation-gate.test.js tests/flow-hooks-research-gate.test.js tests/flow-hooks-loop-check.test.js tests/flow-hooks-manager-boundary-gate.test.js tests/flow-hooks-phase-gate.test.js tests/flow-hooks-pre-tool-orchestrator.test.js tests/flow-hooks-observation-capture.test.js tests/flow-hooks-task-gate.test.js tests/flow-durable-session-suspension.test.js tests/flow-health-mcp-scopes.test.js tests/flow-lean-config.test.js tests/flow-workspace-autopickup.test.js tests/flow-worker-boundary-gate.test.js tests/flow-worker-question-classifier.test.js tests/flow-completion-truth-gate-contradictions.test.js tests/flow-structure-sensor.test.js tests/flow-workspace-dispatch-tracking.test.js tests/workspace-ipc-sqlite.test.js tests/workspace-ipc-multi-worker.test.js tests/flow-story-gates.test.js tests/flow-workspace-restart-handoff.test.js tests/flow-wogi-claude-wrapper.test.js tests/flow-wave1-integrations.test.js tests/flow-wave2-integrations.test.js tests/flow-wave3-integrations.test.js tests/flow-commit-claims-gate.test.js tests/auto-review.test.js tests/gate-telemetry-surface.test.js tests/agents-md-alias.test.js tests/flow-skill-manage.test.js tests/fuzzy-patch.test.js tests/mode-schema.test.js tests/flow-feature-dossier.test.js tests/flow-autonomous-mode.test.js tests/flow-epic-cascade.test.js tests/flow-workspace-summary.test.js tests/flow-hooks-research-evidence-gate.test.js tests/flow-worker-mcp-strip.test.js tests/flow-orchestrate-corrections.test.js tests/flow-source-fidelity.test.js tests/flow-hooks-long-input-enforcement.test.js tests/workspace-channel-tracking.test.js tests/flow-hooks-deletion-log.test.js tests/flow-task-boundary-reset.test.js tests/flow-deferral-gate.test.js tests/flow-research-required-gate.test.js tests/flow-standards-forbidden-patterns.test.js tests/flow-hooks-architect-required-gate.test.js && NODE_ENV=test node tests/run-quality-gates.test.js",
     "test:syntax": "find scripts/ lib/ -name '*.js' -not -path '*/node_modules/*' -exec node --check {} +",
     "lint": "eslint scripts/ lib/ tests/",
     "lint:ci": "eslint scripts/ lib/ tests/ --max-warnings 0",

package/scripts/flow-architect-pass.js

@@ -479,6 +479,20 @@ function recordTelemetry({ taskId, parseResult, gateResult, runCtx = {} }) {
       sessionId: runCtx.sessionId ?? null,
     },
   });
+
+  // wf-037f8d66: Write Architect-run marker for the architect-required PreToolUse gate.
+  // Marker proves Architect ran for this task — gate consults it before allowing
+  // Edit/Write/Bash in coding phase for L1+ tasks. Fail-open on any error.
+  if (taskId && (telemetryVerdict === 'PASS' || telemetryVerdict === 'PASS_WITH_NOTES')) {
+    try {
+      const archGate = require('./hooks/core/architect-required-gate');
+      archGate.writeArchitectRunMarker({
+        taskId,
+        model: runCtx.model || null,
+        plan: parseResult?.plan ? { sections: sectionsPresent } : null,
+      });
+    } catch (_err) { /* fail-open */ }
+  }
 }
 
 // ============================================================

package/scripts/flow-standards-checker.js

@@ -77,23 +77,23 @@ const MATCH_LEVEL_SEVERITY = {
 };
 
 // Task type to check type mapping for smart scoping
-// wf-00c5067b: 'hook-three-layer' added to all task types — entry-file LOC
-// + import-count rule (per .claude/rules/architecture/hook-three-layer.md)
-// is universally applicable; the exemption list in config covers known
-// pre-extraction violators (see ARCH-001, ARCH-002 in .workflow/state/last-audit.json).
+// wf-00c5067b: 'hook-three-layer' added — entry-file LOC + import-count rule.
+// wf-037f8d66: 'forbidden-patterns' added — declarative project-specific
+// patterns (agnosticism rules, no-hardcoding rules, etc.) loaded from
+// .workflow/state/forbidden-patterns.json. Empty file = no-op.
 const TASK_CHECK_MAP = {
-  'component': ['naming', 'components', 'security', 'hook-three-layer'],
-  'utility': ['naming', 'functions', 'security', 'hook-three-layer'],
-  'api': ['naming', 'api', 'security', 'hook-three-layer'],
-  'feature': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer'],
-  'bugfix': ['naming', 'security', 'hook-three-layer'],
-  'refactor': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer'],
-  'story': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer'],
-  'default': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer']
+  'component': ['naming', 'components', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'utility': ['naming', 'functions', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'api': ['naming', 'api', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'feature': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'bugfix': ['naming', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'refactor': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'story': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer', 'forbidden-patterns'],
+  'default': ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer', 'forbidden-patterns']
 };
 
 // All available check types
-const ALL_CHECK_TYPES = ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer'];
+const ALL_CHECK_TYPES = ['naming', 'components', 'functions', 'api', 'schemas', 'services', 'security', 'hook-three-layer', 'forbidden-patterns'];
 
 // ============================================================================
 // Parse Standards Files
@@ -639,6 +639,140 @@ function checkHookThreeLayer(file, hookThreeLayerConfig = {}) {
   return violations;
 }
 
+/**
+ * wf-037f8d66 — Check forbidden patterns from project's declarative rule pack.
+ *
+ * Projects declare their forbidden patterns in `.workflow/state/forbidden-patterns.json`.
+ * This is the GENERIC, DATA-DRIVEN counterpart to checkSecurityPatterns (which is
+ * source-coded). Projects can encode "agnosticism" rules, "no-hardcoding" rules,
+ * "no-claude-code-literal-outside-docs" rules, etc., without modifying the checker.
+ *
+ * Format (forbidden-patterns.json):
+ *   [
+ *     {
+ *       "id": "no-claude-code-literal",
+ *       "pattern": "['\"]claude-code['\"]",      // RegExp source string
+ *       "flags": "g",                             // optional, defaults to 'g'
+ *       "exemptions": ["docs/**", "*.md", "reference/**"],
+ *       "severity": "must-fix",                   // 'must-fix' | 'warning'
+ *       "message": "wogiflow-cli is agnostic; ..."
+ *     }
+ *   ]
+ *
+ * @param {Object} file — { path, content }
+ * @param {Object[]} patterns — array of pattern entries
+ * @returns {Object[]} violations
+ */
+function checkForbiddenPatterns(file, patterns) {
+  const violations = [];
+  if (!Array.isArray(patterns) || patterns.length === 0) return violations;
+
+  const content = file.content || '';
+  const relPath = file.path.startsWith('/')
+    ? path.relative(PATHS.root, file.path)
+    : file.path;
+
+  for (const entry of patterns) {
+    if (!entry || typeof entry !== 'object') continue;
+    if (!entry.pattern || typeof entry.pattern !== 'string') continue;
+
+    // Exemption check (glob match against relative path)
+    const exemptions = Array.isArray(entry.exemptions) ? entry.exemptions : [];
+    const exempted = exemptions.some(glob => globMatch(relPath, glob));
+    if (exempted) continue;
+
+    // Compile regex
+    let re;
+    try {
+      const flags = entry.flags && typeof entry.flags === 'string' ? entry.flags : 'g';
+      re = new RegExp(entry.pattern, flags);
+    } catch (_err) {
+      // Invalid regex — skip (don't crash check)
+      continue;
+    }
+
+    // Match
+    let match;
+    re.lastIndex = 0;
+    while ((match = re.exec(content)) !== null) {
+      const before = content.substring(0, match.index);
+      const lineNumber = (before.match(/\n/g) || []).length + 1;
+      violations.push({
+        type: 'forbidden-pattern',
+        severity: entry.severity === 'warning' ? 'warning' : 'must-fix',
+        file: file.path,
+        line: lineNumber,
+        message: entry.message || `Forbidden pattern matched: ${entry.id || entry.pattern}`,
+        rule: `forbidden-patterns.json: ${entry.id || '(unnamed)'}`
+      });
+
+      // Avoid infinite loop on zero-length matches
+      if (match.index === re.lastIndex) re.lastIndex++;
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Minimal glob-to-regex matcher for forbidden-pattern exemptions.
+ * Supports: `**` (any depth), `*` (no path separator), exact match.
+ * Per security-patterns.md §4: use `[^/]*` not `.*` to prevent path
+ * separator matching in `*` (only `**` should cross directories).
+ */
+function globMatch(filePath, glob) {
+  const normalized = filePath.replace(/\\/g, '/');
+  // Build regex from glob
+  let re = '^';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      // ** matches anything including separators
+      re += '.*';
+      i += 2;
+      // Skip a following / so '**/foo' matches both 'foo' and 'a/b/foo'
+      if (glob[i] === '/') i++;
+    } else if (c === '*') {
+      re += '[^/]*';
+      i++;
+    } else if (c === '?') {
+      re += '[^/]';
+      i++;
+    } else if ('.^$+(){}[]|\\'.includes(c)) {
+      re += '\\' + c;
+      i++;
+    } else {
+      re += c;
+      i++;
+    }
+  }
+  re += '$';
+  try {
+    return new RegExp(re).test(normalized);
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Load forbidden-patterns.json from project state dir.
+ * @returns {Object[]} pattern entries (empty array if missing/invalid)
+ */
+function loadForbiddenPatterns(projectRoot) {
+  const root = projectRoot || PATHS.root;
+  const filePath = path.join(root, '.workflow', 'state', 'forbidden-patterns.json');
+  if (!fs.existsSync(filePath)) return [];
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed;
+  } catch (_err) {
+    return [];
+  }
+}
+
 function checkApiDuplication(file, existingEndpoints, matchConfig) {
   const violations = [];
   const content = file.content || '';
@@ -1090,6 +1224,8 @@ function runStandardsCheck(files, options = {}) {
   const functions = checksToRun.includes('functions') ? parseFunctionMap() : [];
   const endpoints = checksToRun.includes('api') ? parseApiMap() : [];
   const rulesFiles = checksToRun.includes('security') ? loadRulesDir() : [];
+  // wf-037f8d66: load forbidden-patterns.json (empty array if missing)
+  const forbiddenPatterns = checksToRun.includes('forbidden-patterns') ? loadForbiddenPatterns() : [];
 
   // Load schema/service registries if needed
   const schemas = checksToRun.includes('schemas') ? parseSchemaMap() : [];
@@ -1115,7 +1251,8 @@ function runStandardsCheck(files, options = {}) {
     'service-map.md': { checked: checksToRun.includes('services') && services.length > 0, violations: 0 },
     'naming-conventions': { checked: checksToRun.includes('naming'), violations: 0 },
     'security-patterns': { checked: checksToRun.includes('security'), violations: 0 },
-    'hook-three-layer': { checked: checksToRun.includes('hook-three-layer'), violations: 0 }
+    'hook-three-layer': { checked: checksToRun.includes('hook-three-layer'), violations: 0 },
+    'forbidden-patterns': { checked: checksToRun.includes('forbidden-patterns') && forbiddenPatterns.length > 0, violations: 0 }
   };
 
   for (const file of files) {
@@ -1181,6 +1318,13 @@ function runStandardsCheck(files, options = {}) {
       allViolations.push(...hookViolations);
       checksSummary['hook-three-layer'].violations += hookViolations.length;
     }
+
+    // Forbidden patterns from project rule pack (wf-037f8d66)
+    if (checksToRun.includes('forbidden-patterns') && forbiddenPatterns.length > 0) {
+      const fpViolations = checkForbiddenPatterns(file, forbiddenPatterns);
+      allViolations.push(...fpViolations);
+      checksSummary['forbidden-patterns'].violations += fpViolations.length;
+    }
   }
 
   // Count must-fix violations
@@ -1415,6 +1559,9 @@ module.exports = {
   checkRegistryDuplication,
   checkSecurityPatterns,
   checkHookThreeLayer,
+  checkForbiddenPatterns, // wf-037f8d66: declarative project rule pack
+  loadForbiddenPatterns, // wf-037f8d66: exposed for tests + external use
+  globMatch, // wf-037f8d66: exposed for unit testing
   extractDeclaredNames,
   discoverAllRegistries,
   collectReuseCandidates,

package/scripts/hooks/core/architect-required-gate.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow - Architect-Required Gate (wf-037f8d66)
+ *
+ * Closes the methodology gap where the IGR Architect/Adversary pass at
+ * spec_review IS specced (per .claude/docs/phases/02-spec.md) but enforcement
+ * is prompt-only — the agent can skip Architect and go straight to coding.
+ *
+ * This gate fires on Edit/Write during the `coding` phase for L1+ tasks when
+ * config.intentGroundedReasoning.enabled is true and no evidence of an
+ * Architect run exists for the current task.
+ *
+ * Evidence marker: `.workflow/state/architect-runs/<task-id>.json` written
+ * by flow-architect-pass.js on successful completion.
+ *
+ * Scope:
+ *   - L0 (epic) / L1 (story) tasks: Architect required → gate enforces
+ *   - L2 / L3 tasks: skip spec_review entirely (correctly) → gate is a no-op
+ *
+ * Fail-open: any error reading state/config → allow tool call. Same pattern
+ * as research-evidence-gate.js.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { PATHS } = require('../../flow-utils');
+
+const ARCHITECT_RUNS_DIR = path.join(PATHS.state, 'architect-runs');
+
+/**
+ * Compute path to the Architect-run evidence marker for a task.
+ */
+function getArchitectRunPath(taskId) {
+  if (!taskId || typeof taskId !== 'string') return null;
+  return path.join(ARCHITECT_RUNS_DIR, `${taskId}.json`);
+}
+
+/**
+ * Write an Architect-run evidence marker. Called by flow-architect-pass.js
+ * on successful completion. Atomic write-temp + rename.
+ *
+ * @param {Object} payload — { taskId, completedAt, model, plan }
+ * @returns {{ written: boolean, path: string|null }}
+ */
+function writeArchitectRunMarker(payload) {
+  if (!payload || !payload.taskId) {
+    return { written: false, path: null };
+  }
+  try {
+    if (!fs.existsSync(ARCHITECT_RUNS_DIR)) {
+      fs.mkdirSync(ARCHITECT_RUNS_DIR, { recursive: true });
+    }
+    const filePath = getArchitectRunPath(payload.taskId);
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, JSON.stringify({
+      taskId: payload.taskId,
+      completedAt: payload.completedAt || new Date().toISOString(),
+      model: payload.model || null,
+      plan: payload.plan || null
+    }, null, 2));
+    fs.renameSync(tmpPath, filePath);
+    return { written: true, path: filePath };
+  } catch (_err) {
+    return { written: false, path: null };
+  }
+}
+
+/**
+ * Check whether an Architect run is recorded for a given task.
+ * @param {string} taskId
+ * @returns {boolean}
+ */
+function hasArchitectRun(taskId) {
+  const p = getArchitectRunPath(taskId);
+  if (!p) return false;
+  try {
+    return fs.existsSync(p);
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Determine whether the current task requires Architect (L1+ only).
+ * @param {Object} taskMeta — task record from ready.json (has level, type)
+ * @returns {boolean}
+ */
+function requiresArchitect(taskMeta) {
+  if (!taskMeta || typeof taskMeta !== 'object') return false;
+  const level = (taskMeta.level || '').toUpperCase();
+  // L0 (epic) and L1 (story) require Architect.
+  // L2 (task) / L3 (subtask) bypass spec_review correctly.
+  return level === 'L0' || level === 'L1';
+}
+
+/**
+ * Read whether the gate is enabled from config.
+ * Default: enabled when IGR is enabled.
+ */
+function isGateEnabled(config) {
+  const igr = config?.intentGroundedReasoning;
+  if (!igr || igr.enabled === false) return false;
+  // Explicit toggle on the gate itself overrides
+  if (config?.architectRequiredGate?.enabled === false) return false;
+  return true;
+}
+
+/**
+ * Main gate check.
+ *
+ * @param {Object} ctx — { phase, taskId, taskMeta, config, toolName }
+ * @returns {{ blocked: boolean, reason?: string, message?: string }}
+ */
+function checkArchitectRequired(ctx) {
+  const { phase, taskId, taskMeta, config, toolName } = ctx || {};
+
+  // Only fires on tools that mutate state (Edit/Write/Bash/TodoWrite)
+  const mutationTools = new Set(['Edit', 'Write', 'TodoWrite', 'Bash']);
+  if (!toolName || !mutationTools.has(toolName)) {
+    return { blocked: false };
+  }
+
+  // Only fires during coding phase
+  if (phase !== 'coding') {
+    return { blocked: false };
+  }
+
+  // Gate disabled (or IGR off)
+  if (!isGateEnabled(config)) {
+    return { blocked: false };
+  }
+
+  // No active task → not in scope (gate doesn't apply)
+  if (!taskId) {
+    return { blocked: false };
+  }
+
+  // L2/L3 tasks bypass spec_review correctly — gate is a no-op
+  if (!requiresArchitect(taskMeta)) {
+    return { blocked: false };
+  }
+
+  // Check for evidence marker
+  if (hasArchitectRun(taskId)) {
+    return { blocked: false };
+  }
+
+  // Block: Architect required but no evidence
+  return {
+    blocked: true,
+    reason: 'architect-required',
+    message: [
+      `ARCHITECT-REQUIRED GATE: task ${taskId} is L1+ in coding phase but no `,
+      `Architect run is recorded at ${getArchitectRunPath(taskId)}.\n\n`,
+      `Per .claude/docs/phases/02-spec.md Step 1.55, L1+ tasks must run an `,
+      `Architect pass before coding. Invoke:\n\n`,
+      `  node scripts/flow-architect-pass.js run --task=${taskId}\n\n`,
+      `Then retry your edit. To opt out for this task only, set `,
+      `config.architectRequiredGate.enabled = false (project-level), or use `,
+      `\`flow architect-skip --task=${taskId} --reason="..."\` (single-task escape; `,
+      `not yet implemented — opens follow-up wf if needed).`
+    ].join('')
+  };
+}
+
+module.exports = {
+  checkArchitectRequired,
+  writeArchitectRunMarker,
+  hasArchitectRun,
+  requiresArchitect,
+  getArchitectRunPath,
+  isGateEnabled,
+  ARCHITECT_RUNS_DIR
+};

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

@@ -58,6 +58,15 @@ function loadGateDeps() {
     if (process.env.DEBUG) console.error(`[Hook] Phase-read gate not loaded: ${_err.message}`);
   }
 
+  // wf-037f8d66: Architect-required gate (mechanical Layer 2 enforcement)
+  let checkArchitectRequired = () => ({ blocked: false });
+  try {
+    const arg = require('./architect-required-gate');
+    checkArchitectRequired = arg.checkArchitectRequired;
+  } catch (_err) {
+    if (process.env.DEBUG) console.error(`[Hook] Architect-required gate not loaded: ${_err.message}`);
+  }
+
   let recordEvidenceRead = () => {};
   let checkSpecWriteGate = _phaseNoop;
   let clearResearchEvidence = () => {};
@@ -168,6 +177,7 @@ function loadGateDeps() {
     checkRoutingGate, clearRoutingPending, hasActiveTask,
     checkPhaseGate, checkCommitLogGate,
     recordPhaseRead, checkPhaseReadGate, clearPhaseReads,
+    checkArchitectRequired, // wf-037f8d66
     recordEvidenceRead, checkSpecWriteGate, clearResearchEvidence,
     checkDeployGate, checkWriteBlock,
     checkStrikeGate, checkBugfixScope, checkScopeMutation,

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

@@ -118,6 +118,51 @@ function runPreToolGates(ctx, deps) {
     }
   }
 
+  // Architect-required gate (wf-037f8d66)
+  // L1+ tasks in coding phase must have run Architect/Adversary before any Edit/Write/Bash.
+  // L2/L3 tasks bypass spec_review entirely (correctly), so the gate is a no-op there.
+  // Fail-open on any error.
+  if (typeof deps.checkArchitectRequired === 'function' &&
+      (toolName === 'Edit' || toolName === 'Write' || toolName === 'Bash' || toolName === 'TodoWrite')) {
+    try {
+      // Resolve current phase + task meta from active state
+      const flowUtils = require('../../flow-utils');
+      const flowIo = require('../../flow-io');
+      let phase = 'idle';
+      let taskId = null;
+      let taskMeta = null;
+      try {
+        const phaseStatePath = path.join(flowUtils.PATHS.state, 'workflow-phase.json');
+        const ps = flowIo.safeJsonParse(phaseStatePath, null);
+        if (ps) {
+          phase = ps.phase || 'idle';
+          taskId = ps.taskId || null;
+        }
+      } catch (_err) { /* fail-open */ }
+      if (taskId) {
+        try {
+          const ready = flowUtils.getReadyData ? flowUtils.getReadyData() : null;
+          const inProgress = (ready && Array.isArray(ready.inProgress)) ? ready.inProgress : [];
+          taskMeta = inProgress.find(t => t && t.id === taskId) || null;
+        } catch (_err) { /* fail-open */ }
+      }
+
+      const archResult = deps.checkArchitectRequired({
+        phase, taskId, taskMeta, config, toolName
+      });
+      if (archResult.blocked) {
+        return {
+          allowed: false,
+          blocked: true,
+          reason: archResult.reason || 'architect-required',
+          message: archResult.message,
+        };
+      }
+    } catch (_err) {
+      if (process.env.DEBUG) console.error(`[Hook] Architect-required gate error (fail-open): ${_err.message}`);
+    }
+  }
+
   // wf-f9912af6: Deferral-authorization gate. Blocks Write/Edit to
   // last-review.json / last-audit.json when the new content introduces
   // `status: deferred*` on findings without explicit user authorization.