@xulthekl/team-flow 0.22.4 → 0.24.0

package/tests/lib/guard-compound-captured.test.mjs

@@ -0,0 +1,92 @@
+// tests/lib/guard-compound-captured.test.mjs
+// v0.24.0: compound-captured guard — executing:closing must require learnings.md
+// or explicit compound_skipped=true in state.
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+// Import the check function directly for unit-level testing.
+const { checkCompoundCaptured } = await import(
+  join(ROOT, 'scripts', 'guard', 'checks', 'compound-captured.mjs')
+);
+
+function makeDir(prefix) {
+  return mkdtempSync(join(tmpdir(), `tf-compound-${prefix}-`));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+describe('compound-captured guard', () => {
+  describe('learnings.md existence', () => {
+    let dir;
+    before(() => { dir = makeDir('learnings'); });
+    after(() => cleanup(dir));
+
+    it('SHALL fail when no learnings.md and no compound_skipped', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+      assert.ok(result.failures.length > 0);
+      assert.match(result.failures[0], /Compound capture missing/);
+    });
+
+    it('SHALL pass when learnings.md exists and is non-empty', () => {
+      writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+
+    it('SHALL fail when learnings.md exists but is empty', () => {
+      writeFileSync(join(dir, 'learnings.md'), '');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+      assert.match(result.failures[0], /empty/);
+    });
+  });
+
+  describe('compound_skipped explicit opt-out', () => {
+    let dir;
+    before(() => { dir = makeDir('skip'); });
+    after(() => cleanup(dir));
+
+    it('SHALL pass when compound_skipped=true and no learnings.md', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\ncompound_skipped: true\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+
+    it('SHALL fail when compound_skipped=false (not opted out)', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\ncompound_skipped: false\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+    });
+  });
+
+  describe('no state file (backward compatibility)', () => {
+    let dir;
+    before(() => { dir = makeDir('no-state'); });
+    after(() => cleanup(dir));
+
+    it('SHALL fail when no state file and no learnings.md', () => {
+      // No .team-flow.yaml, no learnings.md — guard should still fail
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+    });
+
+    it('SHALL pass when no state file but learnings.md exists', () => {
+      writeFileSync(join(dir, 'learnings.md'), '# Learnings\nContent.\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+  });
+});

package/tests/lib/guard-specs-merged.test.mjs

@@ -27,6 +27,8 @@ function makeChangeDir(withDelta) {
     ? '## ADDED Requirements\n\n### Requirement: New\n\nThe system SHALL do new.\n\n#### Scenario: New\n- **WHEN** x\n- **THEN** y\n'
     : '## Requirements\n\n### Requirement: Existing\n\nThe system SHALL exist.\n\n#### Scenario: Existing\n- **WHEN** a\n- **THEN** b\n';
   writeFileSync(join(dir, 'specs', 'test.md'), specsContent);
+  // v0.24.0: compound-captured dimension requires learnings.md
+  writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
   initializeGitRepository(dir);
   return dir;
 }

package/tests/lib/guard-tests-passing.test.mjs

@@ -25,6 +25,8 @@ function makeChangeDir() {
   writeFileSync(join(dir, 'tasks.md'), '# Tasks\n\n- [x] Task 1\n- [x] Task 2\n');
   writeFileSync(join(dir, 'specs', 'test.md'), '## ADDED Requirements\n\n### Requirement: Test\n\nThe system SHALL test.\n\n#### Scenario: Test\n- **WHEN** test\n- **THEN** test\n');
   writeFileSync(join(dir, 'execution-contract.md'), '# Execution Contract\n\n## Intent Lock\nTest.\n');
+  // v0.24.0: compound-captured dimension requires learnings.md
+  writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
   initializeGitRepository(dir);
   return dir;
 }

package/tests/lib/guard.test.mjs

@@ -312,6 +312,8 @@ describe('guard: execution control records', () => {
   function recordPassingClosingPrerequisites() {
     runNodeScript(CLI_PATH, ['state', 'set', dir, 'test_result', 'pass: unit tests']);
     runNodeScript(CLI_PATH, ['state', 'set', dir, 'spec_merged', 'true']);
+    // v0.24.0: compound-captured dimension requires learnings.md (or explicit skip)
+    writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nCaptured during guard test.\n');
   }
 
   function writeReviewReport(name, content = 'Review completed without blocking findings.\n') {

package/tests/lib/solutions-capture.test.mjs

@@ -0,0 +1,108 @@
+// tests/lib/solutions-capture.test.mjs
+// Tests for scripts/lib/solutions-capture.mjs — compound capture mechanism
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: captureRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-capture.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-capture-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+describe('solutions-capture', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = makeDir();
+  });
+
+  after(() => {
+    // Clean up all temp dirs
+    cleanup(dir);
+  });
+
+  it('creates experience file in correct phase directory', () => {
+    const result = captureRun({
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high',
+      summary: 'OAuth token refresh fails silently', dir,
+    });
+
+    assert.equal(result.phase, 'prd');
+    assert.equal(result.severity, 'high');
+    assert.match(result.file, /^prd\/\d{4}-\d{2}-\d{2}-.*\.md$/);
+
+    // Verify file exists and has frontmatter
+    const filePath = join(dir, result.file);
+    assert.ok(existsSync(filePath), 'experience file should exist');
+    const content = readFileSync(filePath, 'utf-8');
+    assert.match(content, /^---\nphase: prd\n/);
+    assert.match(content, /domain: auth/);
+    assert.match(content, /type: pitfall/);
+    assert.match(content, /severity: high/);
+  });
+
+  it('creates INDEX.md from scratch when missing', () => {
+    captureRun({
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium',
+      summary: 'Parallel test execution race condition', dir,
+    });
+
+    const indexPath = join(dir, 'INDEX.md');
+    assert.ok(existsSync(indexPath), 'INDEX.md should be created');
+    const content = readFileSync(indexPath, 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /parallel test execution/i);
+  });
+
+  it('appends to existing INDEX.md', () => {
+    captureRun({ phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', summary: 'First issue', dir });
+    captureRun({ phase: 'spec', domain: 'api', type: 'insight', severity: 'low', summary: 'Second issue', dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /First issue/);
+    assert.match(content, /Second issue/);
+  });
+
+  it('handles Chinese characters in summary (slugify)', () => {
+    const result = captureRun({
+      phase: 'review', domain: 'frontend', type: 'pitfall', severity: 'high',
+      summary: '中文标题测试特殊字符', dir,
+    });
+
+    assert.ok(result.file.includes('review/'), 'file should be in review phase');
+    assert.ok(existsSync(join(dir, result.file)), 'file with Chinese slug should exist');
+  });
+
+  it('uses cross-phase as default when no phase specified', () => {
+    const result = captureRun({ dir });
+    assert.equal(result.phase, 'cross-phase');
+    assert.equal(result.domain, 'general');
+    assert.equal(result.severity, 'medium');
+  });
+
+  it('rejects invalid phase', () => {
+    // capture calls process.exit(1) on invalid phase
+    // We test by checking that the function does not create files
+    const origExit = process.exit;
+    let exitCode = null;
+    process.exit = (code) => { exitCode = code; };
+    try {
+      captureRun({ phase: 'invalid-phase', dir });
+    } catch { /* ignore */ }
+    process.exit = origExit;
+    assert.equal(exitCode, 1, 'should exit with code 1 for invalid phase');
+  });
+});

package/tests/lib/solutions-index-gen.test.mjs

@@ -0,0 +1,147 @@
+// tests/lib/solutions-index-gen.test.mjs
+// Tests for scripts/lib/solutions-index-gen.mjs — full INDEX.md rebuild
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: indexGenRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-index-gen.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-indexgen-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+function writeEntry(dir, phase, filename, fm) {
+  const phaseDir = join(dir, phase);
+  mkdirSync(phaseDir, { recursive: true });
+  const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(join(phaseDir, filename), `---\n${fmLines}\n---\n\n${fm.summary || 'Body text'}\n`, 'utf-8');
+}
+
+describe('solutions-index-gen', () => {
+  let dir;
+
+  beforeEach(() => { dir = makeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('rebuilds INDEX.md from phase directories', () => {
+    writeEntry(dir, 'prd', '2026-07-01-auth-issue.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'build', '2026-07-02-ci-pattern.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /auth-issue/);
+    assert.match(content, /ci-pattern/);
+  });
+
+  it('sorts by severity descending (high before medium before low)', () => {
+    writeEntry(dir, 'prd', 'low.md', {
+      phase: 'prd', domain: 'd1', type: 'pitfall', severity: 'low', date: '2026-07-03',
+    });
+    writeEntry(dir, 'prd', 'high.md', {
+      phase: 'prd', domain: 'd2', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'medium.md', {
+      phase: 'prd', domain: 'd3', type: 'pitfall', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const highPos = content.indexOf('d2');
+    const medPos = content.indexOf('d3');
+    const lowPos = content.indexOf('d1');
+    assert.ok(highPos < medPos, 'high should appear before medium');
+    assert.ok(medPos < lowPos, 'medium should appear before low');
+  });
+
+  it('sorts by date descending within same severity', () => {
+    writeEntry(dir, 'prd', 'older.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'newer.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-15',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const newerPos = content.indexOf('2026-07-15');
+    const olderPos = content.indexOf('2026-07-01');
+    assert.ok(newerPos < olderPos, 'newer date should appear before older date');
+  });
+
+  it('scans all 7 phase directories', () => {
+    const phases = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
+    for (const phase of phases) {
+      writeEntry(dir, phase, `2026-07-01-${phase}-entry.md`, {
+        phase, domain: 'general', type: 'insight', severity: 'medium', date: '2026-07-01',
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    for (const phase of phases) {
+      assert.match(content, new RegExp(phase), `INDEX should contain ${phase} entries`);
+    }
+  });
+
+  it('skips non-.md files', () => {
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    writeFileSync(join(dir, 'build', 'readme.txt'), 'Not a markdown file', 'utf-8');
+    writeEntry(dir, 'build', '2026-07-01-real.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', date: '2026-07-01',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.doesNotMatch(content, /readme\.txt/);
+    assert.match(content, /real\.md/);
+  });
+
+  it('truncates to 150 entries (drops lowest priority)', () => {
+    // Create 155 entries (all high severity, varying dates)
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    for (let i = 0; i < 155; i++) {
+      const day = String((i % 28) + 1).padStart(2, '0');
+      writeEntry(dir, 'build', `entry-${String(i).padStart(3, '0')}.md`, {
+        phase: 'build', domain: `d${i}`, type: 'pattern', severity: 'high', date: `2026-07-${day}`,
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 150, 'INDEX should be truncated to 150 entries');
+  });
+
+  it('handles empty solutions directory', () => {
+    // No phase directories exist
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 0);
+  });
+});

package/tests/lib/solutions-inject.test.mjs

@@ -0,0 +1,115 @@
+// tests/lib/solutions-inject.test.mjs
+// Tests for scripts/lib/solutions-inject.mjs — compound injection mechanism
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: injectRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-inject.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-inject-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+const INDEX_HEADER = `# Solutions Index
+<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
+| date | phase | domain | type | severity | summary | file |
+|------|-------|--------|------|----------|---------|------|
+`;
+
+function writeIndex(dir, rows) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'INDEX.md'), INDEX_HEADER + rows.join('\n') + '\n', 'utf-8');
+}
+
+describe('solutions-inject', () => {
+  let dir;
+
+  beforeEach(() => { dir = makeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('returns empty when no INDEX.md exists', () => {
+    const result = injectRun({ phase: 'prd', dir });
+    assert.deepEqual(result.entries, []);
+  });
+
+  it('filters by exact phase match', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | high | PRD auth issue | prd/f1.md |',
+      '| 2026-07-01 | build | auth | pitfall | high | Build auth issue | build/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].summary, 'PRD auth issue');
+  });
+
+  it('includes cross-phase entries for any phase query', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | cross-phase | general | pattern | high | Global pattern | cross-phase/f1.md |',
+      '| 2026-07-01 | prd | auth | pitfall | high | PRD issue | prd/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'build', dir });
+    // cross-phase matches for any phase
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].phase, 'cross-phase');
+  });
+
+  it('filters by domain (exact match)', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | high | Auth issue | prd/f1.md |',
+      '| 2026-07-01 | prd | billing | pitfall | high | Billing issue | prd/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', domain: 'auth', dir });
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].domain, 'auth');
+  });
+
+  it('domain "general" matches any query', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | general | pattern | high | General pattern | prd/f1.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', domain: 'auth', dir });
+    assert.equal(result.entries.length, 1);
+  });
+
+  it('sorts by severity descending (high > medium > low)', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | low | Low issue | prd/f1.md |',
+      '| 2026-07-01 | prd | auth | pitfall | high | High issue | prd/f2.md |',
+      '| 2026-07-01 | prd | auth | pitfall | medium | Medium issue | prd/f3.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries[0].severity, 'high');
+    assert.equal(result.entries[1].severity, 'medium');
+    assert.equal(result.entries[2].severity, 'low');
+  });
+
+  it('limits to top-5 entries', () => {
+    const rows = [];
+    for (let i = 0; i < 10; i++) {
+      rows.push(`| 2026-07-0${(i % 9) + 1} | prd | auth | pitfall | high | Issue ${i} | prd/f${i}.md |`);
+    }
+    writeIndex(dir, rows);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries.length, 5, 'should cap at top-5');
+  });
+
+  it('returns empty for no matching entries', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | build | ci | pattern | high | Build issue | build/f1.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.deepEqual(result.entries, []);
+  });
+});