refactor: rename dream → learning; consolidate .devflow/dream/ + .devflow/decisions/ → .devflow/learning/

[dean0x]

Summary

The "dream" placeholder codename (capture hooks + background agent + decisions pipeline) is renamed to learning end-to-end. Directories consolidate to a flat .devflow/learning/; agent Dream→Learning (shared/agents/learning.md, directive --- LEARNING MAINTENANCE --- with subagent_type="Learning"); CLI devflow decisions→devflow learning (clean break, no alias); init flags --learning/--no-learning; feature toggles move to a neutral .devflow/config.json {memory, learning, knowledge} (legacy decisions key coalesces and wins); tuning config decisions.json→learning.json (project .devflow/learning/learning.json + global ~/.devflow/learning.json); TS modules per naming map (feature-config.ts, learning.ts, learning-tuning-config.ts, learning-queue-cleanup.ts, legacy-hooks.ts, HUD learning-counts.ts); shell layer (LEARNING_DIR, _QG_LEARNING, learning-lock).

Changes

Naming Boundary: Content identifiers deliberately KEEP their names (decisions.md, pitfalls.md, decisions-ledger.jsonl, decisions-log.jsonl, index.md, decisions_status, DECISIONS_CONTEXT, decisions_load(), render-decisions.cjs, decisions-format.cjs, decisions-usage-scan.cjs, ADR-NNN/PF-NNN) — user data compatibility.

Migrations: New consolidate-dream-decisions-to-learning-v1 (per-project: config-first with legacy-key coalesce, queue + content moves via moveFile/moveDirContents, 9-entry skip-set drops locks/telemetry, index re-render) + rename-global-decisions-config-v1 (global). The hazardous retired-pipeline migrations purge-learning-pipeline-v1/purge-learning-global-v1 (which would have destroyed the new .devflow/learning/) are deleted; consolidate-to-devflow-dir learning-handling neutralized (ID unchanged). Legacy sweeps: LEGACY_AGENT_NAMES += 'dream', LEGACY_HOOK_FILES += 'dream-lock'; build-plugins.ts now prunes shared-agent copies absent from plugin manifests.

Scope: Explicitly out of scope / unchanged: learnings stay local + gitignored (git-tracking was evaluated and dropped — gitignore functional lines, sentinel, and marker version byte-unchanged); no devflow decisions alias; queue-emptiness stays the sole directive gate (no new locks/throttles/state); 900s staleness, 120s memory throttle, 200→100 queue cap unchanged.

Documentation: Docs rewritten to the learning end-state (CLAUDE.md, README, cli-reference incl. removal of documented-but-unimplemented --review/--purge, file-organization, working-memory, docs-framework); feature KB dream-capture-system replaced by learning-capture-system.

Verification

• Full suite: Test Files 63 passed (63) / Tests 1988 passed (1988); build deterministic (npm run build + build:mds leave the tree clean).
• Pipeline: 3 sequential Coders + Simplifier + Scrutinizer (fixed a real P0: repointed remaining .devflow/decisions/index.md consumers in MDS partials/shared agents/release command) + Evaluator (final verdict ALIGNED — 30/30 acceptance criteria incl. AC-P5) + Tester (11/11 scenario seeds PASS against sandboxed fixtures: full migration, idempotent re-init, clean break, stale-agent sweep, HUD, directive gating, global tuning rename).

Known Follow-Ups

• Pre-existing test flake: build-mds.test.ts temp fixture (commands/_test-dest-safety.mds) can race the rename-completeness sweep scan in learning-agent.test.ts under full-suite parallelism (observed once, second run clean).
• Snyk code scan skipped in this session (MCP unauthenticated).

Related Issues

None specified in this PR.

[dean0x]

Code Review: PR #261 — Rename Dream → Learning

Status: ⚠️ CHANGES_REQUESTED

Summary: This is a well-executed rename refactor with strong end-state correctness. However, there are 9 blocking/should-fix issues that must be resolved before merge. Multiple reviewers independently flagged the same items (dead file, half-renamed symbols, stale comments), elevating priority.

---

Blocking Issues (Must Fix Before Merge)

1. HIGH: Test-isolation TOCTOU race in learning-agent.test.ts:189-201

Confidence: 88% (Testing)

The lockstep artifact sweep at lines 189-201 collects a file list via readdir, then reads each file with readFileSync unguarded. In parallel, test fixtures planted by build-mds.test.ts can be deleted between the sweep's readdir and readFileSync, causing ENOENT crashes.

Fix: Guard file reads with try/catch for ENOENT:

for (const f of files) {
  let content: string;
  try {
    content = fsSync.readFileSync(f, 'utf-8');
  } catch (e) {
    if ((e as NodeJS.ErrnoException).code === 'ENOENT') continue;
    throw e;
  }
  if (content.includes('.devflow/dream/')) violations.push(path.relative(ROOT, f));
}

Apply the same guard to the subagent_type="Dream" sweep at line 207.

---

2. HIGH: Dead scripts/hooks/dream-lock file shipped but unused

Confidence: 97% (Consistency 95% + Reliability 92%)

This PR added scripts/hooks/learning-lock (the renamed version) but left the old scripts/hooks/dream-lock in place. Nothing sources dream-lock anymore — the old file is dead code.

Fix: git rm scripts/hooks/dream-lock (keep the LEGACY_HOOK_FILES('dream-lock') cleanup entry in init.ts so existing user installs get cleaned up).

---

3. MEDIUM: Half-renamed writeDreamConfig alias at src/cli/commands/init.ts:43

Confidence: 88% (Consistency)

The import was repointed from dream-config.js to feature-config.js, but the alias name stayed "Dream":

import { writeConfig as writeDreamConfig } from '../utils/feature-config.js';

This function now writes memory/learning/knowledge toggles — nothing to do with "dream". The alias is a stale name left on a changed line.

Fix: Drop the alias:

import { writeConfig } from '../utils/feature-config.js';
// ... later:
await writeConfig(gitRoot, { memory, learning, knowledge })

---

4. MEDIUM: Consolidate migration step 6 render call unguarded after irreversible moves

File: src/cli/utils/migrations.ts:1073-1074
Confidence: 82% (Testing)

The await renderDecisionsIndex(ctx.projectRoot) call has zero test coverage and no try/catch. If the renderer throws after step 5's irreversible file moves, the migration strands in a broken state with a stale index.md.

Fix:

• Wrap in try/catch that pushes to warnings instead of throwing post-move
• Inject rendererPath into tests so step 6 can be exercised (currently the test skips it)

---

5. MEDIUM: Consolidate migration run() spans 96 lines with duplicated coalesce logic

File: src/cli/utils/migrations.ts:983-1081
Confidence: 84% (Complexity)

Step 1's config block (lines 1008-1019) re-implements the exact decisions → learning coalesce that coerceConfig in feature-config.ts owns. They can't be unified (intentional differences), but the boilerplate duplication is maintainability debt. Also hardcodes { memory: true, learning: true, knowledge: true } instead of using DEFAULT_CONFIG.

Fix:

• Extract step 1 into a named helper seedFeatureConfigFromDream()
• Export DEFAULT_CONFIG from feature-config.ts
• This drops the run() body to ~70 lines, matching the file's pattern of delegating steps to helpers

---

Should-Fix Issues (Address While Code is Open)

6. MEDIUM: Dead path constructors re-pathed instead of deleted

File: src/cli/utils/project-paths.ts:100, :130, :135
Confidence: 85% (Architecture)

Three unused path constructors were re-pathed from .devflow/decisions/ → .devflow/learning/ instead of deleted:

• getDecisionsManifestPath() (line 100)
• getDecisionsNotificationsPath() (line 130)
• getDecisionsBatchIdsPath() (line 135)

Grep confirms zero production references — only the path constructors, their mirrors in project-paths.cjs, and test assertions exist. Ironically, this PR's consolidate migration explicitly lists all three as orphaned.

Fix: Delete the three functions and their exports. Remove the test cases at project-paths.test.ts:247-253.

---

7. MEDIUM: handleConfigure global write bypasses canonical DEVFLOW_DIR accessor

File: src/cli/commands/learning.ts:191
Confidence: 80% (Architecture)

The --configure --global branch writes directly to $HOME/.devflow/learning.json, but every reader uses getDevFlowDirectory(). This breaks for users with DEVFLOW_DIR set — written config is never read back.

Fix: Replace hardcoded path with getDevFlowDirectory():

path.join(getDevFlowDirectory(), 'learning.json')

---

8. MEDIUM: Feature KB mislabels migrations as per-project

File: .devflow/features/learning-capture-system/KNOWLEDGE.md:218
Confidence: 90% (Documentation)

The Migrations section says "Two per-project migrations" but then lists both consolidate-dream-decisions-to-learning-v1 (per-project) AND rename-global-decisions-config-v1 (global). The per-project vs global distinction is load-bearing for D37 fresh-clone edge case reasoning.

Fix: Reword to reflect scope:

One per-project migration (consolidate-dream-decisions-to-learning-v1) and one global migration 
(rename-global-decisions-config-v1) consolidate older installs:

---

9. MEDIUM: Stale "Dream" comments in changed code

Files:

• src/cli/commands/init.ts:1170 — "spawns the Dream agent" → Learning agent
• src/cli/commands/init.ts:1155 — "see the dream hook below"
• src/cli/commands/init.ts:1203 — "Write dream config.json" → ".devflow/config.json"
• src/cli/commands/init.ts:1206 — "dream-config.ts" → "feature-config.ts"
• src/cli/utils/migrations.ts:828 — "runs as the directive-spawned Dream agent" → Learning agent
• src/cli/utils/migrations.ts:888 — "next Dream run" → Learning run
• scripts/hooks/memory-worker:3 — "Dream System: memory-worker" → Learning System
• CLAUDE.md:58 — "NO Dream task" → NO Learning task

Confidence: 90% (Consistency)

These are stale references left during the rename. A reader trusting "spawns the Dream agent" will be misled.

Fix: Replace all occurrences with the Learning equivalents.

---

Additional Suggestions (60–79% Confidence)

1. Weak lockstep 900s assertion — expect(hookContent).toMatch(/900/) only checks for substring presence; it doesn't verify the threshold context. Strengthen with anchored context.

2. Export DEFAULT_CONFIG — Removes the hardcoded literal at migrations.ts:1008 and unifies feature config initialization.

3. Stale parameter name — dreamDir in sweepLegacyDreamMarkers should be renamed to learningDir or oldDreamDir to clarify.

4. JSDoc precedence inverted — src/cli/utils/feature-config.ts:25 JSDoc says "mirrors manifest kb→knowledge" but implementation is backwards. Reword to match code.

5. .decisions-usage.json missing from file tree — Still actively written but dropped from the CLAUDE.md runtime file tree; re-add for completeness.

---

Pre-Existing Issues (Not Blocking This PR)

Several stale "Dream" comments exist in untouched files:

• scripts/hooks/lib/mkdir-lock.cjs:21,31
• scripts/hooks/resolve-project-root:11
• src/cli/commands/capture.ts:9-10

These are pre-existing and can be addressed in a separate sweep.

---

Risk Assessment

• Security: ✓ Clean
• Functional Correctness: ✓ Clean (full compile pass, no dangling imports)
• Architecture: ✓ Sound
• Performance: ✓ No regression
• Test Coverage: ⚠️ One flake introduced, two coverage gaps (fixable)
• Consistency: ⚠️ End-state residue violates ADR-003 (high priority given PR scope)

---

Merge Recommendation

STATUS: CHANGES_REQUESTED — Fix items 1-9 above before merge.

This is a well-executed rename refactor. The functional rename is complete and correct. The issues are consistency/cleanliness concerns appropriate to the PR's scope ("clean end-state per ADR-003"). Multiple reviewers independently flagged the same dead file, orphaned comments, and half-renamed symbols, elevating their priority.

---

Reviewed by: 10 agents (security, architecture, performance, complexity, consistency, regression, testing, reliability, typescript, documentation)
Review Date: 2026-07-15_2239
Branch: refactor/rename-dream-to-learning → main

---

Generated by Claude Code / Devflow Code Review — Review Reports

[dean0x]

[Testing] HIGH (88%) — TOCTOU race: file list via readdir can be stale when readFileSync runs; if build-mds.test.ts deletes transient fixtures between calls, test crashes with ENOENT. Fix: guard reads with try/catch for ENOENT, continue on file not found.

[dean0x]

[Testing/Reliability] MEDIUM (82%) — renderDecisionsIndex called after irreversible dir moves with no try/catch; if throw occurs post-move, migration strands in broken state. Fix: wrap in try/catch→warn, inject rendererPath into tests.

[dean0x]

[Architecture] MEDIUM (80%) — handleConfigure writes to $HOME/.devflow/learning.json but readers use getDevFlowDirectory(); silent no-op when DEVFLOW_DIR is set. Fix: route through canonical accessor via getDevFlowDirectory().

[dean0x]

[Consistency] MEDIUM (88%) — alias 'writeConfig as writeDreamConfig' repointed to feature-config.js but name retained; function now writes {memory,learning,knowledge}, unrelated to dream. Fix: drop alias or rename to writeFeatureConfig.

[dean0x]

[Architecture] MEDIUM (85%) — dead getDecisionsManifestPath re-pathed instead of deleted; builds path for files this PR's consolidate migration drops (zero production refs). Fix: delete the constructor and test case.

[dean0x]

[Complexity] MEDIUM (84%) — 96-line run() duplicates coerceConfig coalesce logic and hardcodes DEFAULT_CONFIG; maintainability debt. Fix: extract seedFeatureConfigFromDream helper, export DEFAULT_CONFIG, drop run() to ~70 lines.

[dean0x]

[Consistency/Documentation] MEDIUM (90%) — 'NO Dream task' is stale; KB renamed to Learning. Fix: change to 'NO Learning task'.

[dean0x]

[Documentation] MEDIUM (90%) — mislabels both migrations as per-project, but rename-global-decisions-config-v1 is global (load-bearing for D37). Fix: relabel one per-project, one global.

[dean0x]

[Documentation] MEDIUM (85%) — JSDoc says 'mirrors manifest kb→knowledge' but implementation is reversed: knowledge from manifest wins, then decisions→learning. Fix: reword to match precedence.