wogiflow 2.34.1 → 2.34.2

package/scripts/hooks/core/worker-continuation-gate.js

@@ -185,6 +185,138 @@ function escalateBlocked({ workspaceRoot, repoName, taskId, reason, managerPort
   } catch (_err) { /* best effort */ }
 }
 
+/**
+ * Is autonomous walk-away mode active for this worker? Read from the canonical
+ * session-state.json. Tailors the stall directive (pre-approved → proceed) but
+ * does NOT change the never-idle guarantee — that holds in all worker mode.
+ */
+function isAutonomousActive(stateDir) {
+  try {
+    const { safeJsonParse } = require('../../flow-utils');
+    const ss = safeJsonParse(path.join(stateDir, 'session-state.json'), null);
+    return Boolean(ss && ss.autonomousMode && ss.autonomousMode.active);
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Directive injected when an in-progress worker is parked at a gate. Tells it to
+ * make real progress by SATISFYING the gate legitimately (read the phase doc,
+ * decompose, provide evidence) — or to channel-escalate — and EXPLICITLY forbids
+ * gate circumvention. This is the integrity half of RC2: never give the worker a
+ * reason to reach for a worktree / marker-write.
+ */
+function buildStallDirective({ taskId, phase, remaining, total, attempt, k, autonomous, env }) {
+  const port = (env && env.WOGI_MANAGER_PORT) || '8800';
+  const repo = (env && env.WOGI_REPO_NAME) || 'worker';
+  const isParked = phase === 'exploring' || phase === 'spec_review';
+  const lines = [
+    `SUSTAINED EXECUTION — task ${taskId} is in progress but appears PARKED (phase=${phase}, ${remaining}/${total || 0} sub-tasks).`,
+    `You are a workspace worker. A dispatched task runs to COMPLETION across turns. Idling silently while a task is in-progress is NOT a valid end-of-turn state.`,
+    '',
+    'Make REAL progress THIS turn by SATISFYING the gate legitimately:'
+  ];
+  if (isParked) {
+    lines.push(
+      `  • You are in the ${phase} phase. Read the required phase instruction file (.claude/docs/phases/), finish the ${phase === 'spec_review' ? 'spec' : 'exploration'}, and advance the pipeline.`,
+      autonomous
+        ? `  • Autonomous mode is ACTIVE → you are PRE-APPROVED. Do NOT wait for spec/architect approval — proceed.`
+        : `  • If this needs manager/user approval, channel-escalate (below) instead of waiting silently.`
+    );
+  } else {
+    lines.push(
+      `  • The task is in an active phase but has no decomposed sub-task ledger yet. Decompose it (TodoWrite) and START the first sub-task, OR if a gate is blocking you, satisfy it (read the required phase doc / provide the required evidence).`
+    );
+  }
+  lines.push(
+    '',
+    'PROHIBITED — gate circumvention is forbidden and pointless (gates resolve phase from the canonical main-repo state, not your cwd):',
+    '  ✗ Do NOT create a git worktree to reach an "ungated" context.',
+    '  ✗ Do NOT hand-write gate-satisfying markers or edit .workflow/state files to fake gate satisfaction.',
+    '  ✗ Do NOT change working directory to dodge a gate.',
+    '',
+    'If you genuinely cannot proceed (blocked on the manager/user, or the next step is destructive / needs credentials), ESCALATE then end the turn:',
+    `  curl -s -X POST http://127.0.0.1:${port} \\`,
+    `    -H "X-Wogi-From: ${repo}" \\`,
+    `    --data-binary "## QUESTION: <your blocker>"`,
+    '',
+    `(stall continuation ${attempt}/${k} — make real progress or escalate; ${k} idle turns in a row will auto-escalate to the manager and stop.)`
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Stall handler (RC1). Drives a proceed-or-escalate continuation for an
+ * in-progress worker task the happy path won't cover, then escalates to the
+ * manager after `noProgressK` consecutive no-progress turns. Shares the per-task
+ * counter file but tracks stall progress in dedicated fields so it never
+ * conflates with the happy-path continuation count. Never returns a silent stop
+ * without having escalated.
+ */
+function handleStall({ stateDir, root, env, taskId, phase, remaining, total, fingerprintFn, cfg }) {
+  let counter = readCounter(stateDir);
+  if (!counter || counter.taskId !== taskId) {
+    counter = { taskId, count: 0, noProgressStreak: 0, fingerprint: null, escalated: false };
+  }
+
+  const fp = fingerprintFn(root, remaining);
+
+  // Use the SAME progress fields as the happy path (fingerprint /
+  // noProgressStreak / escalated). The stall and happy paths are mutually
+  // exclusive per turn but share one task counter; keeping separate fingerprint
+  // fields would break the escalated-resume check when a task transitions
+  // between modes after an escalation (the other mode's fingerprint is null →
+  // resume never fires → worker stuck "already-escalated"). Only `stallCount`
+  // is stall-specific (the attempt display).
+
+  // Respect an existing escalation — only resume if work moved since.
+  if (counter.escalated) {
+    if (counter.fingerprint && fp !== counter.fingerprint) {
+      counter.escalated = false;
+      counter.noProgressStreak = 0;
+    } else {
+      counter.fingerprint = fp;
+      writeCounter(stateDir, counter);
+      return { fired: false, decision: 'allow', reason: 'stall-already-escalated', escalated: true };
+    }
+  }
+
+  // No-progress streak (shared with happy path — no-progress is no-progress
+  // regardless of which mode produced the turn).
+  if (counter.fingerprint != null && fp === counter.fingerprint) {
+    counter.noProgressStreak = (counter.noProgressStreak || 0) + 1;
+  } else {
+    counter.noProgressStreak = 0;
+  }
+  counter.fingerprint = fp;
+
+  // Escalate after K consecutive no-progress turns, then stop.
+  if (counter.noProgressStreak >= cfg.noProgressK) {
+    counter.escalated = true;
+    writeCounter(stateDir, counter);
+    escalateBlocked({
+      workspaceRoot: env.WOGI_WORKSPACE_ROOT, repoName: env.WOGI_REPO_NAME,
+      taskId, reason: `parked at "${phase}" gate with no progress across ${counter.noProgressStreak} turns`,
+      managerPort: env.WOGI_MANAGER_PORT
+    });
+    return { fired: false, decision: 'allow', reason: 'stall-escalated', escalated: true, phase };
+  }
+
+  // Fire a proceed-or-escalate continuation.
+  counter.stallCount = (counter.stallCount || 0) + 1;
+  writeCounter(stateDir, counter);
+  const directive = buildStallDirective({
+    taskId, phase, remaining, total,
+    attempt: counter.noProgressStreak + 1, k: cfg.noProgressK,
+    autonomous: isAutonomousActive(stateDir), env
+  });
+  return {
+    fired: true, decision: 'continue', reason: 'in-progress-stall',
+    taskId, phase, remaining, total, attempt: counter.stallCount, stopReason: directive
+  };
+}
+
 /**
  * Main gate. Returns one of:
  *   { continue: true, stopReason }              — force continuation
@@ -220,20 +352,47 @@ function checkWorkerContinuation(opts = {}) {
       return { fired: false, decision: 'allow', reason: 'no-in-progress' };
     }
 
-    // Active-work phase only (respect spec-approval / exploration waits).
     const phase = readPhase(stateDir);
-    if (!cfg.activePhases.includes(phase)) {
-      return { fired: false, decision: 'allow', reason: `phase-not-active:${phase || 'none'}` };
-    }
+    const fingerprintFn = opts.fingerprintFn || defaultProgressFingerprint;
 
-    // Remaining decomposed work?
+    // Remaining decomposed work (needed by both happy-path and stall fallback).
     const subtaskState = opts.subtaskState || require('../../../lib/workspace-subtask-state');
     const summary = subtaskState.summary(taskId);
     const remaining = summary.remaining;
-    if (remaining <= 0) {
-      return { fired: false, decision: 'allow', reason: 'no-remaining-subtasks' };
+    const total = summary.total;
+
+    const PARKED_PHASES = ['exploring', 'spec_review'];
+    const inActivePhase = cfg.activePhases.includes(phase);
+
+    // Decomposed ledger exists and ALL sub-tasks are complete (total>0,
+    // remaining<=0): the task is wrapping up. Allow a clean stop so the worker
+    // can run `flow done` and task-complete can fire (preserves S2/S6
+    // termination — this is the completion boundary, not a parked stall).
+    if (inActivePhase && remaining <= 0 && total > 0) {
+      return { fired: false, decision: 'allow', reason: 'subtasks-complete' };
     }
 
+    // Stall fallback (RC1, wf-e5e57361): an in-progress worker task that the
+    // happy path won't cover MUST NOT idle silently. Two shapes:
+    //   (a) active phase but NO decomposed ledger ever (total<=0) — e.g. parked
+    //       at an architect / phase-read gate before TodoWrite decomposition.
+    //   (b) parked in an approval / explore phase (exploring / spec_review).
+    // Drive a proceed-or-escalate continuation; escalate to the manager after
+    // noProgressK no-progress turns. Never a silent allow-stop.
+    if ((inActivePhase && total <= 0) || PARKED_PHASES.includes(phase)) {
+      return handleStall({
+        stateDir, root, env, taskId, phase,
+        remaining, total, fingerprintFn, cfg
+      });
+    }
+
+    // Not actionable (idle / routing / completing / unknown) — genuinely allow a
+    // normal stop; there is no in-progress work to sustain here.
+    if (!inActivePhase) {
+      return { fired: false, decision: 'allow', reason: `phase-not-actionable:${phase || 'none'}` };
+    }
+
+    // ── Happy path: active phase + remaining > 0 (unchanged S2 logic) ──
     // Per-task counter (reset when the task changes).
     let counter = readCounter(stateDir);
     if (!counter || counter.taskId !== taskId) {
@@ -243,7 +402,6 @@ function checkWorkerContinuation(opts = {}) {
     // Already escalated for this task ⇒ allow stop (don't re-fire). Manager
     // re-dispatch / restart resets the counter (taskId match but escalated flag);
     // we clear the escalation only when progress resumes (fingerprint changes).
-    const fingerprintFn = opts.fingerprintFn || defaultProgressFingerprint;
     const fingerprint = fingerprintFn(root, remaining);
 
     if (counter.escalated) {
@@ -313,6 +471,9 @@ function checkWorkerContinuation(opts = {}) {
 
 module.exports = {
   checkWorkerContinuation,
+  handleStall,
+  buildStallDirective,
+  isAutonomousActive,
   isWorkerMode,
   getCfg,
   derivedCap,

package/.claude/rules/README.md

@@ -1,36 +0,0 @@
-# Auto-Generated Rules
-
-This directory is auto-generated from `.workflow/state/decisions.md`.
-
-**DO NOT EDIT THESE FILES DIRECTLY.**
-
-Edit `decisions.md` instead, then run:
-```bash
-node scripts/flow-rules-sync.js
-```
-
-Or rules will auto-sync when decisions.md is updated.
-
-## How It Works
-
-- Each section in decisions.md becomes a separate rule file
-- Rules are path-scoped based on section keywords (e.g., "component" rules only load for component files)
-- Claude Code automatically loads these rules for context-aware guidance
-
-## Rule Types
-
-Rules have `alwaysApply` frontmatter that determines loading behavior:
-
-- **`alwaysApply: true`** - Always loaded (rules with: general, always, project, naming, coding, standard, convention, must, never, critical, security in title)
-- **`alwaysApply: false`** - Agent-requested: Claude decides whether to load based on description relevance to current task
-
-This saves tokens by not loading React rules when working on backend code, etc.
-
-## Files
-
-- dual-repo-architecture-2026-02-28.md
-- github-release-workflow-2026-01-30.md
-- alternative-short-name.md
-- alternative-hand-edit-ready-json-to-register-orpha.md
-
-Last synced: 2026-04-24T06:42:44.238Z

package/.claude/rules/_internal/README.md

@@ -1,64 +0,0 @@
----
-alwaysApply: false
-description: "Meta-documentation about how project rules are organized"
----
-# Project Rules
-
-This directory contains coding rules and patterns for this project, organized by category.
-
-## Structure
-
-```
-.claude/rules/
-├── code-style/           # Naming conventions, formatting
-│   └── naming-conventions.md
-├── security/             # Security patterns and practices
-│   └── security-patterns.md
-├── architecture/         # Design decisions and patterns
-│   ├── component-reuse.md
-│   └── model-management.md
-└── README.md
-```
-
-## How Rules Work
-
-Rules are automatically loaded by Claude Code based on:
-- **alwaysApply: true** - Rule is always loaded
-- **alwaysApply: false** - Rule is loaded based on `globs` or `description` relevance
-- **globs** - File patterns that trigger rule loading
-
-## Adding New Rules
-
-1. Choose the appropriate category subdirectory
-2. Create a `.md` file with frontmatter:
-
-```yaml
----
-alwaysApply: false
-description: "Brief description for relevance matching"
-globs: src/**/*.ts  # Optional: only load for these files
----
-```
-
-3. Write the rule content in markdown
-
-## Categories
-
-| Category | Purpose |
-|----------|---------|
-| code-style | Naming conventions, formatting, file structure |
-| security | Security patterns, input validation, safe practices |
-| architecture | Design decisions, component patterns, system organization |
-
-## Auto-Generation
-
-Some rules can be auto-generated from `.workflow/state/decisions.md`:
-
-```bash
-node scripts/flow-rules-sync.js
-```
-
-The sync script will route rules to appropriate category subdirectories.
-
----
-Last updated: 2026-01-12

package/.claude/rules/_internal/document-structure.md

@@ -1,77 +0,0 @@
----
-alwaysApply: false
-description: "All AI-context documents must use PIN markers for targeted context loading"
-globs: ".workflow/**/*.md"
----
-
-# Document Structure for AI Context
-
-All documents in `.workflow/` that are used as AI context MUST follow the PIN standard.
-
-## Required Structure
-
-### 1. Header with PIN List
-Every document starts with a comment listing all pins in the document:
-```markdown
-<!-- PINS: pin1, pin2, pin3 -->
-```
-
-### 2. Section PIN Markers
-Each major section has a PIN marker comment:
-```markdown
-### Section Title
-<!-- PIN: section-specific-pin -->
-[Content]
-```
-
-### 3. PIN Naming Convention
-- Use kebab-case: `user-authentication`, not `userAuthentication`
-- Use semantic names: `error-handling`, not `eh`
-- Use compound names for specificity: `json-parse-safety`
-
-## Why PINs Matter
-
-The PIN system enables:
-1. **Targeted context loading**: Only load sections relevant to current task
-2. **Cheaper model routing**: Haiku can fetch only relevant sections for Opus
-3. **Change detection**: Hash sections independently for smart invalidation
-4. **Cross-reference**: Link sections by PIN across documents
-
-## Example Document
-
-```markdown
-# Config Reference
-
-<!-- PINS: database, authentication, api-keys, environment -->
-
-## Database Settings
-<!-- PIN: database -->
-| Setting | Default | Description |
-|---------|---------|-------------|
-
-## Authentication
-<!-- PIN: authentication -->
-| Setting | Default | Description |
-|---------|---------|-------------|
-```
-
-## Parsing
-
-The PIN system automatically parses documents with:
-- `flow-section-index.js` - Generates section index with pins
-- `flow-section-resolver.js` - Resolves sections by PIN lookup
-- `getSectionsByPins(['auth', 'security'])` - Fetch only relevant sections
-
-## Files That Must Have PINs
-
-| File | Required PINs |
-|------|---------------|
-| `decisions.md` | Per coding rule/pattern |
-| `app-map.md` | Per component/screen |
-| `product.md` | Per product section |
-| `stack.md` | Per technology |
-
-## Validation
-
-Run `node scripts/flow-section-index.js --force` to regenerate the index.
-Check `.workflow/state/section-index.json` for indexed sections and their pins.

package/.claude/rules/_internal/dual-repo-management.md

@@ -1,174 +0,0 @@
----
-alwaysApply: false
-description: "Dual-repo management rules for wogi-flow and wogiflow-cloud"
-globs: "package.json,lib/installer.js,lib/extension-points.js"
----
-# Dual-Repo Management: wogi-flow + wogiflow-cloud
-
-**Added**: 2026-02-28
-**Source**: User directive — formalize dual-repo architecture decisions
-
-## Repository Ownership
-
-| Repo | Package | Visibility | Purpose |
-|------|---------|-----------|---------|
-| `wogi-flow` | `wogiflow` (npm) | Public (AGPL-3.0) | Free CLI, workflow engine, all local-only features |
-| `wogiflow-cloud` | `@wogiflow/teams` (client), `wogiflow-cloud-server` (server) | Private | Teams backend, client hooks, dashboard, portal logic |
-| `wogiflow-portal` | N/A (static site) | Public | wogi.ai — landing page, login, signup, knowledge base |
-
-## Hard Rule: No Teams Code in the Free Repo
-
-Team-specific logic MUST NEVER appear in `wogi-flow`. This includes:
-- Auth/login UI beyond the thin `wogi login`/`wogi logout` adapter
-- Sync engines, presence, real-time features
-- Team CRUD, roles, permissions
-- Dashboard pages
-- Server-side API routes
-
-The free repo provides **extension points** (hooks in `lib/extension-points.js`) that the cloud client plugs into. The adapter pattern is:
-- `wogi-flow` exports hook interfaces and config schema
-- `@wogiflow/teams` imports those interfaces and adds team behavior
-- All team logic executes from `@wogiflow/teams`, never from `wogiflow` core
-
-## Version Management
-
-### Independent Versions, Mutual Awareness
-
-Each repo has its own semver version. They are NOT locked together.
-
-- `wogi-flow` → `package.json` version (currently 1.6.0)
-- `wogiflow-cloud` server → `packages/server/package.json` version (currently 0.1.0)
-- `@wogiflow/teams` client → `packages/client/package.json` version (currently 0.1.0)
-
-### Cross-Repo Version File
-
-Each repo maintains a `.workflow/state/partner-versions.json` that records the last-known version of the other repo:
-
-```json
-// In wogi-flow:
-{
-  "self": { "package": "wogiflow", "version": "1.6.0" },
-  "partners": {
-    "wogiflow-cloud-server": { "version": "0.1.0", "checkedAt": "2026-02-28" },
-    "wogiflow-teams-client": { "version": "0.1.0", "minCompatible": "1.5.0", "checkedAt": "2026-02-28" }
-  }
-}
-
-// In wogiflow-cloud:
-{
-  "self": { "package": "wogiflow-cloud", "version": "0.1.0" },
-  "partners": {
-    "wogiflow": { "version": "1.6.0", "checkedAt": "2026-02-28" }
-  }
-}
-```
-
-**Update rule**: When releasing either repo, update `partner-versions.json` in BOTH repos.
-
-### Compatibility Contract
-
-The `@wogiflow/teams` client declares its minimum compatible `wogiflow` version via peerDependencies:
-
-```json
-"peerDependencies": {
-  "wogiflow": ">=1.5.0"
-}
-```
-
-**When to bump the minimum**:
-- When the free repo removes or renames an exported function that the client uses
-- When the free repo changes the shape of config.json, ready.json, or other state files
-- When the free repo changes hook interfaces (entry point signatures, event payloads)
-
-**When NOT to bump**:
-- New features added to the free repo (additive changes are always compatible)
-- Internal refactoring that doesn't change exports
-
-## Interface Contract (Public API Surface)
-
-The cloud client depends on these interfaces from `wogi-flow`. Changes to any of these require updating the client:
-
-### Exported Functions (from scripts/)
-- `flow-utils.js`: `getConfig()`, `safeJsonParse()`, `writeJson()`, `generateTaskId()`, `validateTaskId()`, `PATHS`, `getReadyData()`, `saveReadyData()`
-- `flow-session-state.js`: `trackTaskStart()`, `trackBypassAttempt()`
-- `flow-memory-blocks.js`: `setCurrentTask()`
-
-### Hook Interfaces (entry point contracts)
-- `PreToolUse` hooks receive: `{ tool, toolInput }` via stdin JSON
-- `PostToolUse` hooks receive: `{ tool, toolInput, toolResult }` via stdin JSON
-- `TaskCompleted` hooks receive: `{ taskId }` via stdin JSON
-- `SessionStart`/`SessionEnd` hooks receive: `{}` via stdin JSON
-
-### State File Formats
-- `ready.json`: `{ inProgress: [], ready: [], blocked: [], recentlyCompleted: [], backlog: [] }`
-- `config.json`: Schema documented in `config.schema.json`
-- `decisions.md`: Markdown with `## Section` / `### Rule` structure
-- `session-state.json`: `{ taskId, status, lastBriefingAt, ... }`
-
-### Config Keys Used by Cloud
-- `hooks.rules.*` — all hook toggle keys
-- `enforcement.*` — strict mode, task gating
-- `semanticMatching.*` — reuse detection thresholds
-
-**When modifying any of the above**: Check wogiflow-cloud for consumers BEFORE releasing.
-
-## Change Propagation Rules
-
-### OSS Change → Does Cloud Need Updating?
-
-| Change Type | Cloud Impact | Action Required |
-|-------------|-------------|-----------------|
-| New feature (additive) | None | No action needed |
-| Bug fix (internal) | None | No action needed |
-| Exported function renamed/removed | BREAKING | Update client, bump peerDep minimum |
-| State file format changed | BREAKING | Update client parsers |
-| Hook interface changed | BREAKING | Update client hooks |
-| Config key renamed/removed | BREAKING | Update client config readers |
-| New config key added | None (additive) | Client can optionally use it |
-
-### Cloud Change → Does OSS Need Updating?
-
-| Change Type | OSS Impact | Action Required |
-|-------------|-----------|-----------------|
-| New server feature | None | No action needed |
-| New client hook | None | No action needed |
-| Client needs new OSS export | REQUIRES | Add export to OSS, release OSS first |
-| Dashboard changes | None | Entirely separate |
-
-### Release Order
-
-1. **OSS first**: If the cloud needs a new OSS feature, release OSS first
-2. **Cloud follows**: Cloud releases independently, referencing the OSS version in peerDeps
-3. **Never**: Release cloud with a dependency on an unreleased OSS version
-
-```
-OSS v1.7.0 (adds new export)
-    ↓
-Cloud client v0.2.0 (uses new export, peerDep bumped to >=1.7.0)
-    ↓
-Cloud server v0.2.0 (may or may not change)
-```
-
-## Web Properties
-
-| Property | Repo | Purpose |
-|----------|------|---------|
-| wogi.ai (main site) | `wogiflow-portal` | Landing, login, signup, knowledge base |
-| Dashboard (admin UI) | `wogiflow-cloud/packages/dashboard/` | Team admin — served by cloud server |
-
-The portal is a separate deployment from the dashboard. The portal is public-facing (marketing + auth). The dashboard is authenticated (team management).
-
-## Verification Checklist (Before Any Release)
-
-### Releasing wogi-flow (OSS):
-1. Check `partner-versions.json` — is cloud version current?
-2. If any exported function/interface changed: grep wogiflow-cloud for consumers
-3. Run `node --check` on all modified scripts
-4. Follow GitHub Release Workflow (decisions.md)
-5. After release: update `partner-versions.json` in wogiflow-cloud
-
-### Releasing wogiflow-cloud:
-1. Check `partner-versions.json` — is OSS version current?
-2. Verify `peerDependencies.wogiflow` range includes current OSS version
-3. If client needs new OSS export: release OSS first
-4. After release: update `partner-versions.json` in wogi-flow

package/.claude/rules/_internal/feature-refactoring-cleanup.md

@@ -1,87 +0,0 @@
----
-alwaysApply: false
-description: "Cleanup checklist when refactoring or renaming features"
-globs:
-  - "scripts/*.js"
-  - ".claude/skills/**/*"
----
-
-# Feature Refactoring Cleanup
-
-When refactoring, renaming, or replacing a feature, ensure complete cleanup of the old implementation.
-
-## Mandatory Cleanup Checklist
-
-When a feature is refactored or renamed, you MUST:
-
-### 1. Remove Old Code
-- [ ] Delete old script files (e.g., `flow-old-feature.js`)
-- [ ] Remove old skill directories (e.g., `.claude/skills/old-feature/`)
-- [ ] Remove old hook files if applicable
-
-### 2. Update Configuration
-- [ ] Rename config keys (e.g., `oldFeature` → `newFeature`)
-- [ ] Remove from `skills.installed` array if skill was removed
-- [ ] Update any feature flags
-
-### 3. Update Documentation
-- [ ] Rename/update doc files in `.claude/docs/`
-- [ ] Update command references in `commands.md`
-- [ ] Update skill-matching.md if skill changed
-- [ ] Search for old name in all `.md` files
-
-### 4. Clean References
-- [ ] Search codebase: `grep -r "old-feature-name" .`
-- [ ] Update imports in dependent scripts
-- [ ] Update any hardcoded references
-
-### 5. Update State Files
-- [ ] Clean `.workflow/state/` of old state files
-- [ ] Update `ready.json` if tasks reference old feature
-- [ ] Archive old change specs
-
-## Search Commands
-
-Run these to find lingering references:
-
-```bash
-# Find all references to old feature
-grep -r "old-feature-name" --include="*.js" --include="*.md" --include="*.json" .
-
-# Find in config
-grep "oldFeatureName" .workflow/config.json
-
-# Find skill references
-grep -r "old-feature" .claude/
-```
-
-## Why This Matters
-
-Incomplete cleanup causes:
-- **Confusion**: Old commands/skills appear to work but don't
-- **Bloat**: Dead code accumulates
-- **Errors**: Old references cause runtime failures
-- **Documentation drift**: Docs describe non-existent features
-
-## Example: transcript-digestion → long-input-gate
-
-When this refactoring happened without proper cleanup:
-
-| Artifact | Status | Should Have Been |
-|----------|--------|------------------|
-| `.claude/skills/transcript-digestion/` | Left behind | Deleted |
-| `config.transcriptDigestion` | Left as-is | Renamed to `longInputGate` |
-| `skills.installed` array | Still listed | Removed |
-| `skill-matching.md` | Old references | Updated |
-| `transcript-digestion.md` doc | Still existed | Renamed/rewritten |
-
-## Automation Opportunity
-
-Consider adding a `flow refactor-cleanup <old-name> <new-name>` command that:
-1. Searches for all references
-2. Shows what needs updating
-3. Optionally auto-updates simple cases
-
----
-
-Last updated: 2026-01-14