@boyingliu01/xp-gate 0.18.5 → 0.19.0

package/plugins/dsh/skills/sprint-flow/__tests__/sprint-flow.test.cjs

@@ -0,0 +1,457 @@
+/**
+ * @test REQ-SF-001 Sprint Flow Trigger Accuracy
+ * @intent Verify that sprint-flow SKILL.md trigger detection correctly distinguishes
+ *        between valid sprint-flow requests and unrelated queries
+ * @covers AC-SF-001-01, AC-SF-001-02, AC-SF-001-03
+ */
+const fs = require('fs');
+const path = require('path');
+
+const SKILL_MD_PATH = path.join(__dirname, '..', 'SKILL.md');
+const REFERENCES_DIR = path.join(__dirname, '..', 'references');
+const PHASE_OVERVIEW_PATH = path.join(REFERENCES_DIR, 'phase-overview.md');
+const PHASE_2_BUILD_PATH = path.join(REFERENCES_DIR, 'phase-3-build.md');
+const ORCHESTRATION_RULES_PATH = path.join(REFERENCES_DIR, 'orchestration-rules.md');
+
+let skillContent = '';
+let phaseOverviewContent = '';
+
+function loadSkillMd() {
+  skillContent = fs.readFileSync(SKILL_MD_PATH, 'utf-8');
+  if (fs.existsSync(PHASE_OVERVIEW_PATH)) {
+    phaseOverviewContent = fs.readFileSync(PHASE_OVERVIEW_PATH, 'utf-8');
+  }
+}
+
+// Search across SKILL.md AND references/phase-overview.md (progressive disclosure: sections
+// like "Unique Value Proposition" and "Phase Flow Consistency" moved to reference file).
+function contentIncludes(str) {
+  return skillContent.includes(str) || phaseOverviewContent.includes(str);
+}
+function contentSplit(str) {
+  // Return the part after str from whichever file contains it.
+  // Throws descriptive error instead of returning undefined so callers
+  // get a clear assertion message rather than a TypeError crash.
+  if (skillContent.includes(str)) return skillContent.split(str)[1];
+  if (phaseOverviewContent.includes(str)) return phaseOverviewContent.split(str)[1];
+  throw new Error(`Section "${str}" not found in SKILL.md or references/phase-overview.md`);
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const yaml = match[1];
+  const result = {};
+  // Parse simple YAML key-value pairs and lists
+  const lines = yaml.split('\n');
+  let currentKey = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const kvMatch = trimmed.match(/^(\w[\w_]*):\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const val = kvMatch[2].trim();
+      if (val === '') {
+        result[currentKey] = [];
+      } else if (val.startsWith('"') || val.startsWith("'")) {
+        result[currentKey] = val.slice(1, -1);
+      } else {
+        result[currentKey] = val;
+      }
+    } else if (trimmed.startsWith('- ') && currentKey) {
+      const item = trimmed.slice(2).trim().replace(/^["'](.*)["'].*$/, '$1');
+      if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+      result[currentKey].push(item);
+    }
+  }
+  return result;
+}
+
+// === Trigger Accuracy Tests ===
+
+function testPositiveTriggersArePresent() {
+  const frontmatter = parseFrontmatter(skillContent);
+  const triggers = frontmatter.triggers || [];
+  const required = ['/sprint-flow', 'start sprint', '开发新功能', '一键开发'];
+  const missing = required.filter(r => !triggers.some(t => t.includes(r)));
+  if (missing.length > 0) {
+    throw new Error(`Missing positive triggers: ${missing.join(', ')}`);
+  }
+  console.log('  ✓ Positive triggers are present');
+}
+
+function testNegativeTriggersArePresent() {
+  const frontmatter = parseFrontmatter(skillContent);
+  const negTriggers = frontmatter.triggers_negative_examples || [];
+  if (negTriggers.length < 8) {
+    throw new Error(`triggers_negative_examples must have at least 8 entries, got ${negTriggers.length}`);
+  }
+  console.log(`  ✓ Negative triggers have ${negTriggers.length} entries (>= 8 required)`);
+}
+
+function testNegativeTriggerPhrases() {
+  // These phrases must NOT trigger sprint-flow
+  const shouldNotTrigger = [
+    '实现排序算法',
+    '实现一下',
+    '帮我实现这个函数',
+    '怎么实现登录功能',
+    'start spring boot',
+    '开发环境配置',
+    '一键部署',
+    '新功能建议',
+    'implement a sort function',
+    'how to implement auth',
+  ];
+  for (const phrase of shouldNotTrigger) {
+    // Verify phrase is in triggers_negative_examples
+    const frontmatter = parseFrontmatter(skillContent);
+    const negTriggers = frontmatter.triggers_negative_examples || [];
+    const found = negTriggers.some(n => n.includes(phrase) || phrase.includes(n));
+    if (!found) {
+      throw new Error(`Negative trigger phrase "${phrase}" not found in triggers_negative_examples`);
+    }
+  }
+  console.log(`  ✓ All ${shouldNotTrigger.length} negative trigger phrases verified`);
+}
+
+function testPositiveTriggerPhrases() {
+  const shouldTrigger = [
+    '开发用户认证模块',
+    '/sprint-flow',
+    '一键开发 REST API',
+  ];
+  for (const phrase of shouldTrigger) {
+    const frontmatter = parseFrontmatter(skillContent);
+    const triggers = frontmatter.triggers || [];
+    // Match against frontmatter triggers OR check body trigger table for broader patterns
+    const matched = triggers.some(t =>
+      phrase.includes(t) || t.includes(phrase) || phrase.includes('/sprint-flow')
+    ) || skillContent.includes(phrase);
+    if (!matched) {
+      throw new Error(`Positive trigger phrase "${phrase}" should match at least one trigger`);
+    }
+  }
+  console.log(`  ✓ All ${shouldTrigger.length} positive trigger phrases verified`);
+}
+
+function testNegativeTestCasesExist() {
+  // Count test case entries by matching "input:" lines in triggers_negative_test_cases YAML block
+  const fmMatch = skillContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) throw new Error('Frontmatter not found');
+  const yaml = fmMatch[1];
+
+  // Find triggers_negative_test_cases block and count "- input:" lines within it
+  const testCasesSection = yaml.split('triggers_negative_test_cases:')[1];
+  if (!testCasesSection) throw new Error('triggers_negative_test_cases not found in frontmatter');
+
+  const count = (testCasesSection.match(/^\s+- input:/gm) || []).length;
+  if (count < 11) {
+    throw new Error(`triggers_negative_test_cases must have at least 11 entries, got ${count}`);
+  }
+  console.log(`  ✓ Negative test cases have ${count} entries (>= 11 required)`);
+}
+
+// === Phase Transition Tests ===
+
+function testWorkflowStepsOrder() {
+  const frontmatter = parseFrontmatter(skillContent);
+  const steps = frontmatter.workflow_steps || [];
+  if (steps.length !== 6) {
+    throw new Error(`workflow_steps must have exactly 6 entries, got ${steps.length}`);
+  }
+
+  const expectedOrder = [
+    'PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE',
+  ];
+
+  for (let i = 0; i < expectedOrder.length; i++) {
+    if (!steps[i].includes(expectedOrder[i])) {
+      throw new Error(
+        `workflow_steps[${i}] should contain "${expectedOrder[i]}", got "${steps[i]}"`
+      );
+    }
+  }
+  console.log('  ✓ workflow_steps order matches canonical 6-phase sequence');
+}
+
+function testPhaseFlowDiagramOrder() {
+  // The Phase Flow diagram in the body must show: PREP → ... → SHIP → CLOSE
+  const flowMatch = skillContent.match(/PREP →.*CLOSE/);
+  if (!flowMatch) {
+    throw new Error('Phase Flow diagram not found in SKILL.md body');
+  }
+  const flow = flowMatch[0];
+
+  // Verify VERIFY comes before SHIP
+  const verifyPos = flow.indexOf('VERIFY');
+  const shipPos = flow.indexOf('SHIP');
+  const closePos = flow.indexOf('CLOSE');
+  if (verifyPos === -1 || shipPos === -1 || closePos === -1) {
+    throw new Error('Phase Flow diagram missing required phases');
+  }
+  if (verifyPos > shipPos) {
+    throw new Error('VERIFY must come before SHIP in phase flow diagram');
+  }
+  if (shipPos > closePos) {
+    throw new Error('SHIP must come before CLOSE in phase flow diagram');
+  }
+  console.log('  ✓ Phase Flow diagram has correct ordering');
+}
+
+function testPhaseFlowConsistencySectionExists() {
+  if (!contentIncludes('Phase Flow Consistency')) {
+    throw new Error('SKILL.md or references/phase-overview.md must contain "Phase Flow Consistency" section');
+  }
+  console.log('  ✓ Phase Flow Consistency section exists');
+}
+
+function testCanonicalPhaseOrderTableExists() {
+  if (!contentIncludes('Canonical Phase Order')) {
+    throw new Error('SKILL.md or references/phase-overview.md must contain "Canonical Phase Order" table');
+  }
+  console.log('  ✓ Canonical Phase Order table exists');
+}
+
+function testAll11PhasesInPhaseFlowConsistency() {
+  const section = contentSplit('Phase Flow Consistency');
+  const requiredPhases = [
+    'PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE',
+  ];
+  for (const phase of requiredPhases) {
+    if (!section.includes(phase)) {
+      throw new Error(`Phase Flow Consistency section missing phase: ${phase}`);
+    }
+  }
+  console.log('  ✓ All 6 phases referenced in Phase Flow Consistency section');
+}
+
+// === Force Levels Tests ===
+
+function testForceLevelsDocumentExists() {
+  const forceLevelsPath = path.join(REFERENCES_DIR, 'force-levels.md');
+  if (!fs.existsSync(forceLevelsPath)) {
+    throw new Error('references/force-levels.md must exist');
+  }
+  const content = fs.readFileSync(forceLevelsPath, 'utf-8');
+  if (!content.includes('轻量') || !content.includes('标准') || !content.includes('复杂')) {
+    throw new Error('force-levels.md must document lightweight/standard/complex levels');
+  }
+  console.log('  ✓ force-levels.md exists and documents three levels');
+}
+
+function testForceLevelsRequiresDelphi() {
+  const forceLevelsContent = fs.readFileSync(
+    path.join(REFERENCES_DIR, 'force-levels.md'), 'utf-8'
+  );
+  if (!forceLevelsContent.includes('Delphi') && !forceLevelsContent.includes('delphi')) {
+    throw new Error('force-levels.md must reference Delphi review requirement');
+  }
+  console.log('  ✓ force-levels.md requires Delphi review for all levels');
+}
+
+// === Value Proposition Tests ===
+
+function testUniqueValuePropositionExists() {
+  if (!contentIncludes('Unique Value Proposition')) {
+    throw new Error('SKILL.md or references/phase-overview.md must contain "Unique Value Proposition" section');
+  }
+  console.log('  ✓ Unique Value Proposition section exists');
+}
+
+function testUvpMentionsTokenSavings() {
+  const section = contentSplit('Unique Value Proposition');
+  if (!section.includes('40') || !section.includes('67') || !section.includes('token')) {
+    throw new Error('Unique Value Proposition must mention 40-67% token savings');
+  }
+  console.log('  ✓ UVP mentions 40-67% token savings');
+}
+
+function testUvpMentionsHardGate() {
+  const section = contentSplit('Unique Value Proposition');
+  if (!section.includes('HARD-GATE')) {
+    throw new Error('Unique Value Proposition must mention HARD-GATE discipline');
+  }
+  console.log('  ✓ UVP mentions HARD-GATE discipline');
+}
+
+function testUvpMentionsEmergentRequirements() {
+  const section = contentSplit('Unique Value Proposition');
+  if (!section.toLowerCase().includes('emergent')) {
+    throw new Error('Unique Value Proposition must mention emergent requirements');
+  }
+  console.log('  ✓ UVP mentions emergent requirements');
+}
+
+// === Phase Timing Tests ===
+
+function testTimingSectionExists() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  if (!phase2BuildContent.includes('Timing & Stability')) {
+    throw new Error('phase-3-build.md must contain "Timing & Stability" section');
+  }
+  console.log('  ✓ Timing & Stability section exists in phase-3-build.md');
+}
+
+function testTimeoutRecommendationsExist() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  const timeoutSection = phase2BuildContent.split('Timing & Stability')[1];
+  if (!timeoutSection || !timeoutSection.includes('Timeout')) {
+    throw new Error('Timing & Stability section must include timeout recommendations');
+  }
+  console.log('  ✓ Timeout recommendations exist');
+}
+
+function testExecutionTimeEstimatesExist() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  if (!phase2BuildContent.includes('Expected Time')) {
+    throw new Error('phase-3-build.md must include expected execution time estimates');
+  }
+  console.log('  ✓ Expected execution time estimates exist');
+}
+
+// === Orchestration Rules Tests ===
+
+function testOrchestrationRulesExists() {
+  if (!fs.existsSync(ORCHESTRATION_RULES_PATH)) {
+    throw new Error('references/orchestration-rules.md must exist');
+  }
+  console.log('  ✓ orchestration-rules.md exists');
+}
+
+function testPhaseSubagentMatrixOrder() {
+  const orchContent = fs.readFileSync(ORCHESTRATION_RULES_PATH, 'utf-8');
+  // The matrix order reflects file names, but phases should all be present
+  for (const phase of ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE']) {
+    if (!orchContent.includes(phase)) {
+      throw new Error(`orchestration-rules.md missing phase: ${phase}`);
+    }
+  }
+  console.log('  ✓ Orchestration rules covers all key phases');
+}
+
+// === Run All Tests ===
+
+function runTests(opts = {}) {
+  const { exitOnFail = false } = opts;
+  let passed = 0;
+  let failed = 0;
+  const errors = [];
+
+  const tests = [
+    { name: 'Positive triggers are present', fn: testPositiveTriggersArePresent },
+    { name: 'Negative triggers have >= 8 entries', fn: testNegativeTriggersArePresent },
+    { name: 'Negative trigger phrases verified', fn: testNegativeTriggerPhrases },
+    { name: 'Positive trigger phrases verified', fn: testPositiveTriggerPhrases },
+    { name: 'Negative test cases exist (>= 11)', fn: testNegativeTestCasesExist },
+    { name: 'workflow_steps order matches canonical', fn: testWorkflowStepsOrder },
+    { name: 'Phase Flow diagram has correct ordering', fn: testPhaseFlowDiagramOrder },
+    { name: 'Phase Flow Consistency section exists', fn: testPhaseFlowConsistencySectionExists },
+    { name: 'Canonical Phase Order table exists', fn: testCanonicalPhaseOrderTableExists },
+    { name: 'All 6 phases in consistency section', fn: testAll11PhasesInPhaseFlowConsistency },
+    { name: 'force-levels.md exists with three levels', fn: testForceLevelsDocumentExists },
+    { name: 'force-levels.md requires Delphi review', fn: testForceLevelsRequiresDelphi },
+    { name: 'Unique Value Proposition exists', fn: testUniqueValuePropositionExists },
+    { name: 'UVP mentions 40-67% token savings', fn: testUvpMentionsTokenSavings },
+    { name: 'UVP mentions HARD-GATE', fn: testUvpMentionsHardGate },
+    { name: 'UVP mentions emergent requirements', fn: testUvpMentionsEmergentRequirements },
+    { name: 'Timing & Stability section exists', fn: testTimingSectionExists },
+    { name: 'Timeout recommendations exist', fn: testTimeoutRecommendationsExist },
+    { name: 'Execution time estimates exist', fn: testExecutionTimeEstimatesExist },
+    { name: 'orchestration-rules.md exists', fn: testOrchestrationRulesExists },
+    { name: 'Orchestration covers all key phases', fn: testPhaseSubagentMatrixOrder },
+    { name: 'Uncommitted Changes Gate section exists', fn: testUncommittedGateExists },
+    { name: 'Uncommitted gate has escape valve', fn: testUncommittedGateEscapeValve },
+    { name: 'Uncommitted gate has log path', fn: testUncommittedGateLogPath },
+  ];
+
+  loadSkillMd();
+
+  for (const { name, fn } of tests) {
+    try {
+      fn();
+      passed++;
+    } catch (e) {
+      failed++;
+      errors.push(`FAIL: ${name}: ${e.message}`);
+    }
+  }
+
+  console.log(`\n=== Results: ${passed} passed, ${failed} failed ===\n`);
+  for (const e of errors) console.log(e);
+
+  if (exitOnFail && failed > 0) {
+    process.exit(1);
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+// Uncommitted Changes Gate tests (must run after the section is added)
+function testUncommittedGateExists() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  if (!phase2BuildContent.includes('Uncommitted Changes Gate')) {
+    throw new Error('phase-3-build.md must contain "Uncommitted Changes Gate" section');
+  }
+  console.log('  ✓ Uncommitted Changes Gate section exists');
+}
+
+function testUncommittedGateEscapeValve() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  if (!phase2BuildContent.includes('SKIP_UNCOMMITTED_GATE')) {
+    throw new Error('Uncommitted Changes Gate must provide SKIP_UNCOMMITTED_GATE escape valve');
+  }
+  console.log('  ✓ Uncommitted gate has SKIP_UNCOMMITTED_GATE escape valve');
+}
+
+function testUncommittedGateLogPath() {
+  const phase2BuildContent = fs.readFileSync(PHASE_2_BUILD_PATH, 'utf-8');
+  if (!phase2BuildContent.includes('.sprint-state/uncommitted-gate-log.json')) {
+    throw new Error('Uncommitted Changes Gate must log to .sprint-state/uncommitted-gate-log.json');
+  }
+  console.log('  ✓ Uncommitted gate logs to .sprint-state/uncommitted-gate-log.json');
+}
+
+// When run directly (node script.js), call with exitOnFail for CLI behavior.
+if (require.main === module) {
+  const exitCode = runTests({ exitOnFail: true });
+  process.exit(exitCode);
+}
+
+// Vitest discovery — wrap each test function as a vitest it() block
+describe('sprint-flow SKILL.md', () => {
+  beforeAll(() => { loadSkillMd(); });
+
+  const tests = [
+    { name: 'Positive triggers are present', fn: testPositiveTriggersArePresent },
+    { name: 'Negative triggers have >= 8 entries', fn: testNegativeTriggersArePresent },
+    { name: 'Negative trigger phrases verified', fn: testNegativeTriggerPhrases },
+    { name: 'Positive trigger phrases verified', fn: testPositiveTriggerPhrases },
+    { name: 'Negative test cases exist (>= 11)', fn: testNegativeTestCasesExist },
+    { name: 'workflow_steps order matches canonical', fn: testWorkflowStepsOrder },
+    { name: 'Phase Flow diagram has correct ordering', fn: testPhaseFlowDiagramOrder },
+    { name: 'Phase Flow Consistency section exists', fn: testPhaseFlowConsistencySectionExists },
+    { name: 'Canonical Phase Order table exists', fn: testCanonicalPhaseOrderTableExists },
+    { name: 'All 6 phases in consistency section', fn: testAll11PhasesInPhaseFlowConsistency },
+    { name: 'force-levels.md exists with three levels', fn: testForceLevelsDocumentExists },
+    { name: 'force-levels.md requires Delphi review', fn: testForceLevelsRequiresDelphi },
+    { name: 'Unique Value Proposition exists', fn: testUniqueValuePropositionExists },
+    { name: 'UVP mentions 40-67% token savings', fn: testUvpMentionsTokenSavings },
+    { name: 'UVP mentions HARD-GATE', fn: testUvpMentionsHardGate },
+    { name: 'UVP mentions emergent requirements', fn: testUvpMentionsEmergentRequirements },
+    { name: 'Timing & Stability section exists', fn: testTimingSectionExists },
+    { name: 'Timeout recommendations exist', fn: testTimeoutRecommendationsExist },
+    { name: 'Execution time estimates exist', fn: testExecutionTimeEstimatesExist },
+    { name: 'orchestration-rules.md exists', fn: testOrchestrationRulesExists },
+    { name: 'Orchestration covers all key phases', fn: testPhaseSubagentMatrixOrder },
+    { name: 'Uncommitted Changes Gate section exists', fn: testUncommittedGateExists },
+    { name: 'Uncommitted gate has escape valve', fn: testUncommittedGateEscapeValve },
+    { name: 'Uncommitted gate has log path', fn: testUncommittedGateLogPath },
+  ];
+
+  for (const { name, fn } of tests) {
+    it(name, () => { fn(); });
+  }
+});
+
+module.exports = { runTests };

package/plugins/dsh/skills/sprint-flow/hooks.md

@@ -0,0 +1,18 @@
+# Hooks — Sprint Flow
+
+Sprint Flow integrates with safety and operational hooks to protect the development environment.
+
+## Security Hooks
+
+| Hook | Purpose | Activation |
+|------|---------|------------|
+| `/careful` | Safety guardrails for destructive commands | Activate before any `rm`, `force-push`, or `git reset` |
+| `/freeze` | Restrict edits to sprint worktree directory | Prevent accidental changes outside sprint scope |
+| `/guard` | Full safety mode (careful + freeze) | Maximum protection for high-risk operations |
+
+## Operational Hooks
+
+| Hook | Purpose | Activation |
+|------|---------|------------|
+| `/context-save` | Save sprint context before pause or handoff | Before pausing sprint or switching tasks |
+| `/context-restore` | Restore sprint context on resume | When resuming from pause or handoff |

package/plugins/dsh/skills/sprint-flow/references/components/memory.md

@@ -0,0 +1,87 @@
+# memory.md — Sprint State JSON Schema 与长期记忆（AHE 组件分解）
+
+> **本文是 `skills/sprint-flow/SKILL.md` 中状态管理 JSON (L190-334) 的 AHE 对齐展开。**
+> 用于 ablation 实验：AHE 论文显示 Memory 组件单独恢复全局增幅的 95%+。
+
+## 组件职责
+
+定义 Sprint 状态持久化 Schema、Phase 输出合同、长期记忆（learnings）结构。是 AHE 中最关键组件（记忆单独恢复 95%+ 全局增益）。
+
+---
+
+## Sprint State Schema（`.sprint-state/sprint-state.json`）
+
+```json
+{
+  "id": "sprint-YYYY-MM-DD-NN",
+  "phase": 0,
+  "status": "running|paused|completed",
+  "outputs": {
+    "pain_document": "docs/pain-document.md",
+    "specification": "specification.yaml",
+    "mvp": "mvp-v1/",
+    "review_report": "review-report.md"
+  },
+  "metrics": {
+    "tests_passed": 15,
+    "tests_failed": 0,
+    "coverage_pct": 85
+  }
+}
+```
+
+### 状态枚举
+
+| 字段 | 允许值 | 说明 |
+|------|-------|------|
+| `phase` | 0-6 | 当前执行阶段 |
+| `status` | `pending` / `running` / `paused` / `completed` / `failed` | 统一状态 |
+| `pause_reason` | `none` / `wait_approved` / `wait_gate1` / `wait_uat` / `wait_ship` / `wait_user_confirm` | 暂停原因 |
+
+---
+
+## Phase Output 合同
+
+| Phase | 输出文件 | 存储路径 | 必需字段 |
+|-------|---------|---------|---------|
+| Phase 0 | `pain-document.md` | `phase-outputs/pain-document.md` | 结构化设计文档 |
+| Phase 1 | `specification.yaml` | `phase-outputs/specification.yaml` | user_stories[], requirements[], acceptance_criteria[] |
+| Phase 2 | `mvp-v1/` | `phase-outputs/mvp-v1/` | 功能代码 + 测试 |
+| Phase 3 | `review-report.md` | `phase-outputs/review-report.md` | delphi-review 共识报告 |
+| Phase 4 | `emergent-issues.md` | `phase-outputs/emergent-issues.md` | 用户发现的 emergent requirements |
+| Phase 5 | `feedback-log.md` | `phase-outputs/feedback-log.md` | 改进建议 + 调试记录 |
+| Phase 6 | `sprint-summary.md` | `phase-outputs/sprint-summary.md` | 发布记录 + Sprint 2 触发判断 |
+
+---
+
+## Sprint 2 自动触发规则
+
+```
+Phase 6 完成后:
+  IF emergent_issues_count == 0 → sprint_completed，结束
+  IF emergent_issues_count > 0 → sprint_2_needed:
+    ├─ IF 有 Critical → 自动启动 Sprint 2
+    ├─ IF 仅有 Major/Minor → 询问用户
+    └─ Sprint 2 Pain Document ← emergent-issues.md 转化
+```
+
+---
+
+## Learnings Schema（长期记忆）
+
+ralph-loop 内部分类:
+- `permanent`: 跨 REQ 持久化（通用约束、模式）
+- `contextual`: 当前 REQ 生命周期内有效
+
+learnings.md 写入分类: permanent / contextual 通过 `.sprint-history/learnings.md` 持久化（原生，替代原 gstack/learn）。
+
+---
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Long-Term Memory |
+| 修改频率预期 | 低（Schema 稳定） |
+| 消融实验假设 | 移除 memory → Sprint pass rate 下降 5-10% |
+| 参考证据 | AHE 论文: Memory 单独恢复 95%+ 全局增幅（事实性 > 策略性） |

package/plugins/dsh/skills/sprint-flow/references/components/middleware.md

@@ -0,0 +1,75 @@
+# middleware.md — Sprint Flow 状态机与暂停点逻辑（AHE 组件分解）
+
+> **本文是 `skills/sprint-flow/SKILL.md` 中完整流程 (L46-68) 和暂停点表 (L72-84) 的 AHE 对齐展开。**
+> 用于 ablation 实验：AHE 论文显示 Middleware 组件贡献占 37%，单独修改可显著影响性能。
+
+## 组件职责
+
+定义 Sprint Flow 的状态机转换逻辑、暂停点（pause-point）触发条件和自动恢复规则。是 phase 间的"胶水层"，负责在特定节点暂停等待用户决策。
+
+---
+
+## 完整状态机（7 Phase 流转）
+
+```
+Phase 0: THINK → brainstorming → HARD-GATE: 设计未 APPROVED → 不可编码
+Phase 1: PLAN  → autoplan → delphi-review → spec.yaml
+Phase 2: BUILD → GITHOOKS-GATE → ralph-loop/TDD → verification → MVP v1
+Phase 3: REVIEW → code-walkthrough → test-alignment → browse QA
+Phase 4: USER ACCEPTANCE → ⚠️ 必须人工 → Emergent Issues List
+Phase 5: FEEDBACK → learn + retro + systematic-debugging
+Phase 6: SHIP → finishing-a-development-branch → canary → Sprint Summary
+```
+
+## 暂停点矩阵
+
+| Phase | 暂停点标识 | 触发条件 | 用户操作 | 自动恢复条件 |
+|-------|-----------|---------|---------|-------------|
+| Phase 0 | **HARD-GATE** | 设计未 APPROVED | 修改设计文档 | 设计 APPROVED 后继续 |
+| Phase 1 | taste_decisions | autoplan 发现未决议事项 | 用户确认每个决策 | 确认后自动继续 |
+| Phase 1 | delphi-review | 最终 REQUEST_CHANGES（subagent 自动修复仍失败） | 修复并重新 dispatch | APPROVED 后自动继续 |
+| **Phase 2** | **DELPHI-GATE** | delphi-reviewed.json 不存在或 verdict != APPROVED | 返回 Phase 1 完成 delphi-review | APPROVED 后继续 |
+| Phase 2 | 验证失败 | 超过 max 3 次失败 | 用户决定修复或放弃 | 验证通过后自动继续 |
+| Phase 2 | 成本超阈值 | token 成本 > 阈值 | 用户决定继续或暂停 | 用户确认后自动继续 |
+| Phase 3 | browse 发现问题 | QA 失败 | 回退 Phase 2 | 验证通过后自动继续 |
+| **Phase 4** | **必须人工验收** | 进入 Phase 4 | 用户实际使用后确认 | **无法自动恢复** |
+| **Phase 5** | **FEEDBACK 硬门禁** | Phase 4 完成后进入 | 执行 learn + retro → 生成 feedback-log.md | feedback-log.md 存在后继续 |
+| **Phase 6** | **Phase 5 门禁验证** | Phase 5 未完成 | 验证 feedback-log.md → 不存在 → 返回 Phase 5 | feedback-log.md 存在后继续 |
+| Phase 6 | finishing-a-branch | 分支收尾 | 用户 4 选 1 | 确认后自动继续 |
+
+> **#218 变更**: Delphi review Round 1→2→3 的自动调度在 subagent 内部完成，不暂停。`delphi-review` 暂停点仅当 subagent 自动修复仍失败时才触发。
+> **#225 变更**: `taste_decisions` 暂停点由 orchestrator 直接执行 autoplan，不 dispatch 到 subagent。
+> **PR 确认冗余移除**: ship PR 创建后不再暂停确认 — 用户已通过 finishing-a-development-branch 选择了 PR 路径。
+
+## 状态转换规则
+
+| 当前状态 | 下一状态 | 条件 |
+|---------|---------|------|
+| Phase N 完成 | Phase N+1 | 无阻塞条件 |
+| Phase 0 HARD-GATE 未通过 | Phase 0 (重试) | 设计未 APPROVED |
+| Phase 2 DELPHI-GATE 未通过 | Phase 1 (回退) | delphi-review not APPROVED |
+| Phase 4 人工验收未完成 | Phase 4 (等待) | **永远不可自动跳过** |
+| Phase 4 确认完成 | Phase 5 | **必须执行，不可跳过** |
+| Phase 5 未完成 (feedback-log.md 不存在) | Phase 5 (等待) | **永远不可自动跳过** |
+| Phase 2 验证失败 > 3 次 | BLOCK (用户决策) | 熔断机制 |
+| Phase 2 成本超限 | BLOCK (用户决策) | 熔断机制 |
+
+## 熔断机制 (Circuit Breaker)
+
+| 原 xp-consensus 状态 | 新处理方案 |
+|---------------------|-----------|
+| `CIRCUIT_BREAKER_TRIGGERED` | sprint-flow 编排层监控成本，超阈值 BLOCK + 用户决策 |
+| `ROLLBACK_TO_ROUND1` | verification-before-completion 失败 → 修复 max 3 次 → 仍失败 BLOCK |
+| `GATE1_FAILED`/`GATE1_COMPLETE` | verification-before-completion 内置此区分 |
+| `GATE2_RUNNING` | `xp-gate check --all`（Gate 7/8/9）— Phase 1-6 安全审计 |
+
+---
+
+## AHE 分类
+
+| 字段 | 值 |
+|------|---|
+| 组件类型 | Middleware |
+| 修改频率预期 | 高（状态机调整频繁） |
+| 消融实验假设 | 修改暂停点逻辑 → Sprint 执行时间变化 ±15% |
+| 参考证据 | AHE 论文: Middleware 组件单独修改带来 +2.2% 总增益 |