cc-devflow 4.1.2 → 4.1.4

package/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.1.4] - 2026-02-08
+
+### 🧭 Workspace Worktree Session Recovery & Release Flow Clarity
+
+v4.1.4 strengthens workspace-to-worktree continuity so developers can resume a requirement reliably across sessions, and clarifies flow init/release semantics in command and skill docs.
+
+#### Added
+
+- **Workspace switch script**
+  - Added `.claude/scripts/flow-workspace-switch.sh`
+  - Supports `REQ/BUG` pointer updates, journal logging, `--print-cd`, and sourced `--cd` switching
+
+- **Scripts architecture map**
+  - Added `.claude/scripts/CLAUDE.md` as L2 directory map for script responsibilities
+
+#### Changed
+
+- **Workspace start behavior**
+  - `.claude/scripts/flow-workspace-start.sh` now accepts `REQ-XXX/BUG-XXX` override
+  - Added `--switch` and sourced `--cd` behavior for faster worktree handoff
+  - Added BUG status file compatibility (`devflow/bugs/*/status.json`)
+
+- **Requirement initialization linkage**
+  - `.claude/scripts/create-requirement.sh` now syncs `devflow/workspace/{developer}/.current-req` when workspace exists
+
+- **Flow docs and skills alignment**
+  - Updated flow init/release/workspace command docs and workflow skills to reflect:
+    - default worktree naming semantics
+    - merge semantics by release strategy
+    - workspace continuity expectations
+
+#### Benefits
+
+- ✅ New session recovery can target the intended REQ/BUG directly
+- ✅ Worktree switching is faster and less error-prone via generated `cd` commands
+- ✅ Flow release semantics are clearer when deciding between PR-only vs merge paths
+
+## [4.1.3] - 2026-02-08
+
+### 🔧 Flow Quality Default Path + AGENTS.md Safe Emit
+
+v4.1.3 aligns release gates with `/flow-quality` as the default path and improves compiler emitters to preserve user-owned AGENTS memory content.
+
+#### Fixed
+
+- **Flow quality/release gate consistency**
+  - `/flow-quality` quick mode now generates minimal `TEST_REPORT.md` and `SECURITY_REPORT.md`
+  - Release entry gate accepts `quality_complete` (with `qa_complete` backward compatibility)
+  - Flow docs/scripts updated to recommend `/flow-quality` by default, with `--full` as enhanced review mode
+
+- **AGENTS.md overwrite prevention in compiler emitters**
+  - Added managed block upsert mechanism in base emitter
+  - Codex/Antigravity emitters now write compact index blocks instead of appending full agent/rule bodies
+  - Existing user memory content in `AGENTS.md` is preserved
+
+#### Added
+
+- **Regression coverage for managed blocks**
+  - Tests for AGENTS managed block generation, idempotence, and preservation behavior
+
+#### Benefits
+
+- ✅ `flow-quality` becomes a true default path to `flow-release` without requiring `--full`
+- ✅ Compiler output no longer clobbers user-maintained AGENTS memory sections
+- ✅ Backward compatibility with legacy QA status remains intact
+
 ## [4.1.2] - 2026-02-07
 
 ### 🔧 Adapt Compiler Migration Reliability Fixes

package/lib/compiler/__tests__/compile-regression.test.js

@@ -74,6 +74,8 @@ describe('compile() regression', () => {
   });
 
   test('should compile nested commands and emit skills for codex', async () => {
+    fs.writeFileSync('AGENTS.md', '# User Memory\n\nKeep this content.\n');
+
     const result = await compile({
       sourceDir: '.claude/commands',
       skillsDir: '.claude/skills',
@@ -90,5 +92,12 @@ describe('compile() regression', () => {
     expect(fs.existsSync('.codex/skills/flow-dev/SKILL.md')).toBe(true);
     expect(fs.existsSync('.codex/skills/orchestrator/SKILL.md')).toBe(true);
     expect(fs.existsSync('AGENTS.md')).toBe(true);
+
+    const agentsContent = fs.readFileSync('AGENTS.md', 'utf8');
+    expect(agentsContent).toContain('# User Memory');
+    expect(agentsContent).toContain('<!-- cc-devflow:codex-agents:start -->');
+    expect(agentsContent).toContain('<!-- cc-devflow:codex-rules:start -->');
+    expect(agentsContent).not.toContain('# planner');
+    expect(agentsContent).not.toContain('# rule');
   });
 });

package/lib/compiler/__tests__/multi-module-emitters.test.js

@@ -213,9 +213,10 @@ describe('CodexEmitter Multi-Module', () => {
     expect(content).toContain('## Required Context');
   });
 
-  test('emitAgents merges to AGENTS.md', async () => {
+  test('emitAgents writes compact managed block and preserves existing content', async () => {
     const sourceDir = path.join(tempDir, '.claude', 'agents');
     const targetPath = path.join(tempDir, 'AGENTS.md');
+    fs.writeFileSync(targetPath, '# User Memory\n\nDo not overwrite this.\n');
 
     const results = await emitter.emitAgents(sourceDir, targetPath);
 
@@ -223,25 +224,32 @@ describe('CodexEmitter Multi-Module', () => {
     expect(fs.existsSync(targetPath)).toBe(true);
 
     const content = fs.readFileSync(targetPath, 'utf8');
-    expect(content).toContain('# Agents');
-    expect(content).toContain('## test-agent');
+    expect(content).toContain('# User Memory');
+    expect(content).toContain('<!-- cc-devflow:codex-agents:start -->');
+    expect(content).toContain('## CC-DevFlow Agents');
+    expect(content).toContain('- Count: 1');
+    expect(content).not.toContain('This agent is for testing.');
   });
 
-  test('emitRules appends to AGENTS.md', async () => {
+  test('emitRules writes compact managed block and remains idempotent', async () => {
     const sourceDir = path.join(tempDir, '.claude', 'rules');
     const targetPath = path.join(tempDir, 'AGENTS.md');
 
-    // 先创建 AGENTS.md
-    fs.writeFileSync(targetPath, '# Agents\n\nExisting content.\n');
+    fs.writeFileSync(targetPath, '# User Memory\n\nKeep me.\n');
 
-    const results = await emitter.emitRules(sourceDir, targetPath);
+    const first = await emitter.emitRules(sourceDir, targetPath);
+    const second = await emitter.emitRules(sourceDir, targetPath);
 
-    expect(results.length).toBe(1);
+    expect(first.length).toBe(1);
+    expect(second.length).toBe(1);
 
     const content = fs.readFileSync(targetPath, 'utf8');
-    expect(content).toContain('# Agents');
-    expect(content).toContain('## Rules');
-    expect(content).toContain('### test-rule');
+    expect(content).toContain('# User Memory');
+    expect(content).toContain('<!-- cc-devflow:codex-rules:start -->');
+    expect(content).toContain('## CC-DevFlow Rules');
+    expect(content).toContain('- Count: 1');
+    expect(content).not.toContain('This rule is for testing.');
+    expect(content.split('<!-- cc-devflow:codex-rules:start -->').length - 1).toBe(1);
   });
 });
 
@@ -428,6 +436,24 @@ describe('AntigravityEmitter Multi-Module', () => {
     const targetPath = path.join(targetDir, 'test-rule.md');
     expect(fs.existsSync(targetPath)).toBe(true);
   });
+
+  test('emitAgents writes compact managed block and preserves existing content', async () => {
+    const sourceDir = path.join(tempDir, '.claude', 'agents');
+    const targetPath = path.join(tempDir, 'AGENTS.md');
+    fs.writeFileSync(targetPath, '# User Memory\n\nKeep this section.\n');
+
+    const results = await emitter.emitAgents(sourceDir, targetPath);
+
+    expect(results.length).toBe(1);
+    expect(fs.existsSync(targetPath)).toBe(true);
+
+    const content = fs.readFileSync(targetPath, 'utf8');
+    expect(content).toContain('# User Memory');
+    expect(content).toContain('<!-- cc-devflow:antigravity-agents:start -->');
+    expect(content).toContain('## CC-DevFlow Agents');
+    expect(content).toContain('- Count: 1');
+    expect(content).not.toContain('This agent is for testing.');
+  });
 });
 
 // ============================================================

package/lib/compiler/emitters/antigravity-emitter.js

@@ -9,7 +9,7 @@
  * 输出格式:
  * - Commands: Markdown + YAML frontmatter -> .agent/workflows/
  * - Skills: SKILL.md (YAML frontmatter) -> .agent/skills/
- * - Agents: 合并到 AGENTS.md
+ * - Agents: 索引摘要写入 AGENTS.md（保留用户内容）
  * - Rules: Markdown -> .agent/rules/
  *
  * 限制: 单文件 <= 12,000 字符，超限时自动拆分
@@ -319,10 +319,29 @@ class AntigravityEmitter extends BaseEmitter {
 
   /**
    * 编译 Agents 模块
-   * .claude/agents/[name].md -> AGENTS.md (合并)
+   * .claude/agents/[name].md -> AGENTS.md (短索引，受管块)
    */
   async emitAgents(sourceDir, targetPath) {
-    return this._defaultAgentsEmit(sourceDir, targetPath);
+    const results = [];
+    const agentNames = await this.readMarkdownEntryNames(sourceDir);
+
+    if (agentNames.length === 0) {
+      return results;
+    }
+
+    const summary = [
+      '## CC-DevFlow Agents',
+      '',
+      '- Scope: `.claude/agents/*.md`',
+      `- Count: ${agentNames.length}`,
+      `- Entries: ${this.formatCompactList(agentNames)}`,
+      '- Policy: Keep AGENTS.md concise; detailed agent instructions stay in source files.'
+    ].join('\n');
+
+    const result = await this.upsertManagedBlock(targetPath, 'antigravity-agents', summary);
+    results.push({ ...result, count: agentNames.length });
+
+    return results;
   }
 
   /**

package/lib/compiler/emitters/base-emitter.js

@@ -23,6 +23,7 @@ const crypto = require('crypto');
 // SECURITY CONFIGURATION (FINDING-003)
 // ============================================================
 const MAX_OUTPUT_SIZE = 2 * 1024 * 1024; // 2MB limit
+const MANAGED_BLOCK_PREFIX = 'cc-devflow';
 
 // ============================================================
 // MODULE_TYPES - 支持的模块类型
@@ -284,6 +285,83 @@ class BaseEmitter {
   hashContent(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
   }
+
+  /**
+   * 读取目录下的 Markdown 文件名（去掉 .md）
+   */
+  async readMarkdownEntryNames(sourceDir) {
+    if (!fs.existsSync(sourceDir)) {
+      return [];
+    }
+
+    const entries = await fs.promises.readdir(sourceDir, { withFileTypes: true });
+
+    return entries
+      .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+      .map(entry => entry.name.replace(/\.md$/, ''))
+      .sort((a, b) => a.localeCompare(b));
+  }
+
+  /**
+   * 格式化短列表，避免全局记忆文件过长
+   */
+  formatCompactList(items, maxItems = 12) {
+    if (!items || items.length === 0) {
+      return '`(none)`';
+    }
+
+    const visible = items.slice(0, maxItems).map(item => `\`${item}\``);
+    const hiddenCount = items.length - visible.length;
+
+    if (hiddenCount > 0) {
+      visible.push(`... (+${hiddenCount} more)`);
+    }
+
+    return visible.join(', ');
+  }
+
+  /**
+   * 受管块写入：仅替换指定区块，保留用户原有内容
+   */
+  async upsertManagedBlock(targetPath, blockId, body) {
+    const startMarker = `<!-- ${MANAGED_BLOCK_PREFIX}:${blockId}:start -->`;
+    const endMarker = `<!-- ${MANAGED_BLOCK_PREFIX}:${blockId}:end -->`;
+    const managedBlock = `${startMarker}\n${body.trim()}\n${endMarker}`;
+
+    let existing = '';
+    if (fs.existsSync(targetPath)) {
+      existing = await fs.promises.readFile(targetPath, 'utf8');
+    }
+
+    const merged = this._replaceManagedBlock(existing, startMarker, endMarker, managedBlock);
+    return this.emitToPath(targetPath, merged);
+  }
+
+  _replaceManagedBlock(existing, startMarker, endMarker, managedBlock) {
+    const startIndex = existing.indexOf(startMarker);
+    const endIndex = existing.indexOf(endMarker);
+
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+      const before = existing.slice(0, startIndex).trimEnd();
+      const after = existing.slice(endIndex + endMarker.length).trimStart();
+
+      return this._joinBlocks(before, managedBlock, after);
+    }
+
+    if (!existing.trim()) {
+      return `${managedBlock}\n`;
+    }
+
+    return `${existing.trimEnd()}\n\n${managedBlock}\n`;
+  }
+
+  _joinBlocks(...blocks) {
+    const validBlocks = blocks.filter(block => block && block.trim().length > 0);
+    if (validBlocks.length === 0) {
+      return '';
+    }
+    return `${validBlocks.join('\n\n')}\n`;
+  }
 }
 
 module.exports = BaseEmitter;

package/lib/compiler/emitters/codex-emitter.js

@@ -9,8 +9,8 @@
  * 输出格式:
  * - Commands: Markdown + YAML frontmatter → .codex/prompts/
  * - Skills: SKILL.md (YAML frontmatter) → .codex/skills/
- * - Agents: 合并到 AGENTS.md
- * - Rules: 合并到 AGENTS.md
+ * - Agents: 索引摘要写入 AGENTS.md（保留用户内容）
+ * - Rules: 索引摘要写入 AGENTS.md（保留用户内容）
  *
  * v2.0: 支持多模块编译
  */
@@ -194,51 +194,54 @@ class CodexEmitter extends BaseEmitter {
 
   /**
    * 编译 Agents 模块
-   * .claude/agents/[name].md -> AGENTS.md (合并)
+   * .claude/agents/[name].md -> AGENTS.md (短索引，受管块)
    */
   async emitAgents(sourceDir, targetPath) {
-    return this._defaultAgentsEmit(sourceDir, targetPath);
+    const results = [];
+    const agentNames = await this.readMarkdownEntryNames(sourceDir);
+
+    if (agentNames.length === 0) {
+      return results;
+    }
+
+    const summary = [
+      '## CC-DevFlow Agents',
+      '',
+      '- Scope: `.claude/agents/*.md`',
+      `- Count: ${agentNames.length}`,
+      `- Entries: ${this.formatCompactList(agentNames)}`,
+      '- Policy: Keep AGENTS.md concise as global memory; full agent specs stay in source files.'
+    ].join('\n');
+
+    const result = await this.upsertManagedBlock(targetPath, 'codex-agents', summary);
+    results.push({ ...result, count: agentNames.length });
+
+    return results;
   }
 
   /**
    * 编译 Rules 模块
-   * .claude/rules/[name].md -> AGENTS.md (追加)
+   * .claude/rules/[name].md -> AGENTS.md (短索引，受管块)
    */
   async emitRules(sourceDir, targetPath) {
     const results = [];
+    const ruleNames = await this.readMarkdownEntryNames(sourceDir);
 
-    if (!fs.existsSync(sourceDir)) {
+    if (ruleNames.length === 0) {
       return results;
     }
 
-    const entries = await fs.promises.readdir(sourceDir, { withFileTypes: true });
-    const sections = [];
-
-    for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) {
-        continue;
-      }
-
-      const filePath = path.join(sourceDir, entry.name);
-      const content = await fs.promises.readFile(filePath, 'utf8');
-      const ruleName = entry.name.replace('.md', '');
-
-      sections.push(`### ${ruleName}\n\n${content}`);
-    }
-
-    if (sections.length > 0) {
-      // 追加到现有 AGENTS.md
-      let existingContent = '';
-      if (fs.existsSync(targetPath)) {
-        existingContent = await fs.promises.readFile(targetPath, 'utf8');
-      }
-
-      const rulesSection = `\n\n## Rules\n\n${sections.join('\n\n---\n\n')}`;
-      const merged = existingContent + rulesSection;
-
-      const result = await this.emitToPath(targetPath, merged);
-      results.push(result);
-    }
+    const summary = [
+      '## CC-DevFlow Rules',
+      '',
+      '- Scope: `.claude/rules/*.md`',
+      `- Count: ${ruleNames.length}`,
+      `- Entries: ${this.formatCompactList(ruleNames)}`,
+      '- Policy: AGENTS.md stores only memory-level constraints, not full rule bodies.'
+    ].join('\n');
+
+    const result = await this.upsertManagedBlock(targetPath, 'codex-rules', summary);
+    results.push({ ...result, count: ruleNames.length });
 
     return results;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.1.2",
+    "version": "4.1.4",
     "description": "DevFlow CLI tool",
     "main": "bin/cc-devflow.js",
     "bin": {