@xulthekl/team-flow 0.22.4

package/src/validation/validator.ts

@@ -0,0 +1,552 @@
+import { ValidationReport, ValidationIssue, ValidationLevel } from './types.js';
+import type { VerificationReport, VerificationFinding, ConflictReport, SyncConflict } from './types.js';
+import {
+  MIN_PURPOSE_LENGTH,
+  MIN_WHY_SECTION_LENGTH,
+  MAX_WHY_SECTION_LENGTH,
+  MAX_REQUIREMENT_TEXT_LENGTH,
+  MAX_DELTAS_PER_CHANGE,
+  VALIDATION_MESSAGES,
+  VERIFICATION_MESSAGES,
+} from './constants.js';
+import { tokenize } from './tokenizer.js';
+import {
+  parseDeltaSpec,
+  normalizeRequirementName,
+  extractRequirementsSection,
+} from '../parsing/requirement-blocks.js';
+
+const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
+const SCENARIO_HEADER_REGEX = /^####\s+Scenario:/i;
+
+function normalizeLineEndings(content: string): string {
+  return content.replace(/\r\n?/g, '\n');
+}
+
+function extractSection(content: string, heading: string): string | undefined {
+  const normalized = normalizeLineEndings(content);
+  const lines = normalized.split('\n');
+  // Match headings that contain the English keyword — supports both
+  // "## Why" and "## 背景（Why）" style bilingual headings.
+  const headingRegex = new RegExp(`^##\\s+.*\\b${heading.replace(/\s+/g, '\\s+')}\\b.*$`, 'i');
+  const idx = lines.findIndex((l) => headingRegex.test(l));
+  if (idx === -1) return undefined;
+
+  let endIdx = lines.length;
+  for (let i = idx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  return lines.slice(idx + 1, endIdx).join('\n').trim();
+}
+
+function containsShallOrMust(text: string): boolean {
+  return /\b(SHALL|MUST)\b/.test(text);
+}
+
+function countScenarios(blockRaw: string): number {
+  const matches = blockRaw.match(/^####\s+/gm);
+  return matches ? matches.length : 0;
+}
+
+function extractRequirementText(blockRaw: string): string | undefined {
+  const lines = blockRaw.split('\n');
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^####\s+/.test(line)) break;
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (/^\*\*[^*]+\*\*:/.test(trimmed)) continue;
+    return trimmed;
+  }
+  return undefined;
+}
+
+function buildMissingShallOrMustMessage(
+  action: 'ADDED' | 'MODIFIED',
+  blockName: string
+): string {
+  const base = `${action} "${blockName}" must contain SHALL or MUST`;
+  if (containsShallOrMust(blockName)) {
+    return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`;
+  }
+  return base;
+}
+
+function formatSectionList(sections: string[]): string {
+  if (sections.length === 0) return '';
+  if (sections.length === 1) return sections[0];
+  const head = sections.slice(0, -1);
+  const last = sections[sections.length - 1];
+  return `${head.join(', ')} and ${last}`;
+}
+
+function enrichTopLevelError(itemId: string, baseMessage: string): string {
+  const msg = baseMessage.trim();
+  if (msg === VALIDATION_MESSAGES.CHANGE_NO_DELTAS) {
+    return `${msg}. ${VALIDATION_MESSAGES.GUIDE_NO_DELTAS}`;
+  }
+  if (
+    msg.includes('Spec must have a Purpose section') ||
+    msg.includes('Spec must have a Requirements section')
+  ) {
+    return `${msg}. ${VALIDATION_MESSAGES.GUIDE_MISSING_SPEC_SECTIONS}`;
+  }
+  if (
+    msg.includes('Change must have a Why section') ||
+    msg.includes('Change must have a What Changes section')
+  ) {
+    return `${msg}. ${VALIDATION_MESSAGES.GUIDE_MISSING_CHANGE_SECTIONS}`;
+  }
+  return msg;
+}
+
+function createReport(issues: ValidationIssue[], strictMode: boolean = false): ValidationReport {
+  const errors = issues.filter((i) => i.level === 'ERROR').length;
+  const warnings = issues.filter((i) => i.level === 'WARNING').length;
+  const info = issues.filter((i) => i.level === 'INFO').length;
+
+  const valid = strictMode ? errors === 0 && warnings === 0 : errors === 0;
+
+  return {
+    valid,
+    issues,
+    summary: { errors, warnings, info },
+  };
+}
+
+export class Validator {
+  private strictMode: boolean;
+
+  constructor(strictMode: boolean = false) {
+    this.strictMode = strictMode;
+  }
+
+  validateSpecContent(specName: string, content: string): ValidationReport {
+    const issues: ValidationIssue[] = [];
+
+    if (!specName || specName.trim().length === 0) {
+      issues.push({ level: 'ERROR', path: 'name', message: VALIDATION_MESSAGES.SPEC_NAME_EMPTY });
+    }
+
+    const purposeSection = extractSection(content, 'Purpose');
+    if (!purposeSection || purposeSection.trim().length === 0) {
+      issues.push({
+        level: 'ERROR',
+        path: 'overview',
+        message: VALIDATION_MESSAGES.SPEC_PURPOSE_EMPTY,
+      });
+    } else if (purposeSection.length < MIN_PURPOSE_LENGTH) {
+      issues.push({
+        level: 'WARNING',
+        path: 'overview',
+        message: VALIDATION_MESSAGES.PURPOSE_TOO_BRIEF,
+      });
+    }
+
+    const reqSectionParts = extractRequirementsSection(content);
+    if (reqSectionParts.bodyBlocks.length === 0) {
+      issues.push({
+        level: 'ERROR',
+        path: 'requirements',
+        message: VALIDATION_MESSAGES.SPEC_NO_REQUIREMENTS,
+      });
+    }
+
+    for (const block of reqSectionParts.bodyBlocks) {
+      const reqText = extractRequirementText(block.raw);
+      if (!reqText || reqText.trim().length === 0) {
+        issues.push({
+          level: 'ERROR',
+          path: `requirements.${block.name}`,
+          message: VALIDATION_MESSAGES.REQUIREMENT_EMPTY,
+        });
+      } else {
+        if (!containsShallOrMust(reqText)) {
+          issues.push({
+            level: 'ERROR',
+            path: `requirements.${block.name}`,
+            message: buildMissingShallOrMustMessage('ADDED', block.name),
+          });
+        }
+        if (reqText.length > MAX_REQUIREMENT_TEXT_LENGTH) {
+          issues.push({
+            level: 'INFO',
+            path: `requirements.${block.name}`,
+            message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
+          });
+        }
+      }
+
+      const scenarioCount = countScenarios(block.raw);
+      if (scenarioCount < 1) {
+        issues.push({
+          level: 'WARNING',
+          path: `requirements.${block.name}.scenarios`,
+          message: `${VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS}. ${VALIDATION_MESSAGES.GUIDE_SCENARIO_FORMAT}`,
+        });
+      }
+    }
+
+    return createReport(issues, this.strictMode);
+  }
+
+  validateChangeContent(changeName: string, content: string): ValidationReport {
+    const issues: ValidationIssue[] = [];
+
+    if (!changeName || changeName.trim().length === 0) {
+      issues.push({ level: 'ERROR', path: 'name', message: VALIDATION_MESSAGES.CHANGE_NAME_EMPTY });
+    }
+
+    const whySection = extractSection(content, 'Why');
+    if (!whySection || whySection.trim().length === 0) {
+      issues.push({
+        level: 'ERROR',
+        path: 'why',
+        message: VALIDATION_MESSAGES.CHANGE_WHY_TOO_SHORT,
+      });
+    } else {
+      if (whySection.length < MIN_WHY_SECTION_LENGTH) {
+        issues.push({
+          level: 'ERROR',
+          path: 'why',
+          message: VALIDATION_MESSAGES.CHANGE_WHY_TOO_SHORT,
+        });
+      }
+      if (whySection.length > MAX_WHY_SECTION_LENGTH) {
+        issues.push({
+          level: 'WARNING',
+          path: 'why',
+          message: VALIDATION_MESSAGES.CHANGE_WHY_TOO_LONG,
+        });
+      }
+    }
+
+    const whatChanges = extractSection(content, 'What Changes');
+    if (!whatChanges || whatChanges.trim().length === 0) {
+      issues.push({
+        level: 'ERROR',
+        path: 'whatChanges',
+        message: VALIDATION_MESSAGES.CHANGE_WHAT_EMPTY,
+      });
+    }
+
+    return createReport(issues, this.strictMode);
+  }
+
+  validateDeltaSpec(content: string): ValidationReport {
+    const issues: ValidationIssue[] = [];
+
+    const plan = parseDeltaSpec(content);
+    const totalDeltas =
+      plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length;
+
+    if (totalDeltas === 0) {
+      issues.push({
+        level: 'ERROR',
+        path: 'file',
+        message: enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS),
+      });
+      return createReport(issues, this.strictMode);
+    }
+
+    if (totalDeltas > MAX_DELTAS_PER_CHANGE) {
+      issues.push({
+        level: 'WARNING',
+        path: 'file',
+        message: VALIDATION_MESSAGES.CHANGE_TOO_MANY_DELTAS,
+      });
+    }
+
+    const addedNames = new Set<string>();
+    const modifiedNames = new Set<string>();
+    const removedNames = new Set<string>();
+    const renamedFrom = new Set<string>();
+    const renamedTo = new Set<string>();
+
+    for (const block of plan.added) {
+      const key = normalizeRequirementName(block.name);
+      if (addedNames.has(key)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'added',
+          message: `Duplicate requirement in ADDED: "${block.name}"`,
+        });
+      } else {
+        addedNames.add(key);
+      }
+      const reqText = extractRequirementText(block.raw);
+      if (!reqText) {
+        issues.push({
+          level: 'ERROR',
+          path: `added.${block.name}`,
+          message: `ADDED "${block.name}" is missing requirement text`,
+        });
+      } else if (!containsShallOrMust(reqText)) {
+        issues.push({
+          level: 'ERROR',
+          path: `added.${block.name}`,
+          message: buildMissingShallOrMustMessage('ADDED', block.name),
+        });
+      }
+      if (countScenarios(block.raw) < 1) {
+        issues.push({
+          level: 'ERROR',
+          path: `added.${block.name}`,
+          message: `ADDED "${block.name}" must include at least one scenario`,
+        });
+      }
+    }
+
+    for (const block of plan.modified) {
+      const key = normalizeRequirementName(block.name);
+      if (modifiedNames.has(key)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'modified',
+          message: `Duplicate requirement in MODIFIED: "${block.name}"`,
+        });
+      } else {
+        modifiedNames.add(key);
+      }
+      const reqText = extractRequirementText(block.raw);
+      if (!reqText) {
+        issues.push({
+          level: 'ERROR',
+          path: `modified.${block.name}`,
+          message: `MODIFIED "${block.name}" is missing requirement text`,
+        });
+      } else if (!containsShallOrMust(reqText)) {
+        issues.push({
+          level: 'ERROR',
+          path: `modified.${block.name}`,
+          message: buildMissingShallOrMustMessage('MODIFIED', block.name),
+        });
+      }
+      if (countScenarios(block.raw) < 1) {
+        issues.push({
+          level: 'ERROR',
+          path: `modified.${block.name}`,
+          message: `MODIFIED "${block.name}" must include at least one scenario`,
+        });
+      }
+    }
+
+    for (const name of plan.removed) {
+      const key = normalizeRequirementName(name);
+      if (removedNames.has(key)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'removed',
+          message: `Duplicate requirement in REMOVED: "${name}"`,
+        });
+      } else {
+        removedNames.add(key);
+      }
+    }
+
+    for (const { from, to } of plan.renamed) {
+      const fromKey = normalizeRequirementName(from);
+      const toKey = normalizeRequirementName(to);
+      if (renamedFrom.has(fromKey)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'renamed',
+          message: `Duplicate FROM in RENAMED: "${from}"`,
+        });
+      } else {
+        renamedFrom.add(fromKey);
+      }
+      if (renamedTo.has(toKey)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'renamed',
+          message: `Duplicate TO in RENAMED: "${to}"`,
+        });
+      } else {
+        renamedTo.add(toKey);
+      }
+    }
+
+    for (const n of modifiedNames) {
+      if (removedNames.has(n)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'cross-section',
+          message: `Requirement present in both MODIFIED and REMOVED: "${n}"`,
+        });
+      }
+      if (addedNames.has(n)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'cross-section',
+          message: `Requirement present in both MODIFIED and ADDED: "${n}"`,
+        });
+      }
+    }
+    for (const n of addedNames) {
+      if (removedNames.has(n)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'cross-section',
+          message: `Requirement present in both ADDED and REMOVED: "${n}"`,
+        });
+      }
+    }
+    for (const { from, to } of plan.renamed) {
+      const fromKey = normalizeRequirementName(from);
+      const toKey = normalizeRequirementName(to);
+      if (modifiedNames.has(fromKey)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'cross-section',
+          message: `MODIFIED references old name from RENAMED. Use new header for "${to}"`,
+        });
+      }
+      if (addedNames.has(toKey)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'cross-section',
+          message: `RENAMED TO collides with ADDED for "${to}"`,
+        });
+      }
+    }
+
+    return createReport(issues, this.strictMode);
+  }
+
+  validateImplementation(
+    diffSummary: string,
+    specContent: string,
+    designContent: string,
+    config?: { verification?: { language?: string } }
+  ): VerificationReport {
+    const dimensions: VerificationReport['dimensions'] = [];
+    const language = (config?.verification?.language as 'auto' | 'en' | 'zh') ?? 'auto';
+
+    // --- Completeness ---
+    const completenessFindings: VerificationFinding[] = [];
+    const requirements = this.extractRequirementNames(specContent);
+    const diffTokens = tokenize(diffSummary, language);
+    for (const req of requirements) {
+      // A requirement is considered covered when every significant token appears
+      // somewhere in the diff tokens. Uses language-aware tokenization so that
+      // both English (stemming) and Chinese (CJK sliding window) are handled.
+      const reqTokens = tokenize(req, language);
+      const allPresent = reqTokens.size === 0 || [...reqTokens].every(t => diffTokens.has(t));
+      if (!allPresent) {
+        completenessFindings.push({
+          level: 'CRITICAL',
+          dimension: 'Completeness',
+          message: VERIFICATION_MESSAGES.COMPLETENESS_MISSING_REQUIREMENT.replace('{requirement}', req),
+        });
+      }
+    }
+    dimensions.push({
+      name: 'Completeness',
+      status: completenessFindings.some(f => f.level === 'CRITICAL') ? 'FAIL' : completenessFindings.length > 0 ? 'WARN' : 'PASS',
+      findings: completenessFindings,
+    });
+
+    // --- Correctness ---
+    const correctnessFindings: VerificationFinding[] = [];
+    const placeholderPatterns = ['TODO', 'FIXME', 'HACK', 'XXX', 'PLACEHOLDER'];
+    for (const pattern of placeholderPatterns) {
+      if (diffSummary.includes(pattern)) {
+        correctnessFindings.push({
+          level: 'CRITICAL',
+          dimension: 'Correctness',
+          message: VERIFICATION_MESSAGES.VERIFICATION_PLACEHOLDER_DETECTED,
+        });
+        break;
+      }
+    }
+    dimensions.push({
+      name: 'Correctness',
+      status: correctnessFindings.some(f => f.level === 'CRITICAL') ? 'FAIL' : correctnessFindings.length > 0 ? 'WARN' : 'PASS',
+      findings: correctnessFindings,
+    });
+
+    // --- Coherence ---
+    const coherenceFindings: VerificationFinding[] = [];
+    const decisionNames = this.extractDecisionNames(designContent);
+    for (const name of decisionNames) {
+      // Tokenize both the decision name and the diff summary using language-aware
+      // tokenization, then check that all decision tokens appear in diff tokens.
+      const decisionTokens = tokenize(name, language);
+      const allPresent = decisionTokens.size === 0 || [...decisionTokens].every(t => diffTokens.has(t));
+      if (!allPresent) {
+        coherenceFindings.push({
+          level: 'IMPORTANT',
+          dimension: 'Coherence',
+          message: VERIFICATION_MESSAGES.COHERENCE_PATTERN_MISSING.replace('{pattern}', name),
+        });
+      }
+    }
+    dimensions.push({
+      name: 'Coherence',
+      status: coherenceFindings.some(f => f.level === 'CRITICAL') ? 'FAIL' : coherenceFindings.length > 0 ? 'WARN' : 'PASS',
+      findings: coherenceFindings,
+    });
+
+    // --- Verdict ---
+    const hasCritical = dimensions.some(d => d.status === 'FAIL');
+    const hasWarning = dimensions.some(d => d.status === 'WARN');
+    const verdict: VerificationReport['verdict'] = hasCritical ? 'FAIL' : hasWarning ? 'CONDITIONAL' : 'PASS';
+
+    return { dimensions, verdict };
+  }
+
+  private extractRequirementNames(specContent: string): string[] {
+    const regex = /### Requirement:\s*(.+)/g;
+    const names: string[] = [];
+    let match;
+    while ((match = regex.exec(specContent)) !== null) {
+      names.push(match[1].trim());
+    }
+    return names;
+  }
+
+  private extractDecisionNames(designContent: string): string[] {
+    const regex = /- Choice:\s*(.+)/g;
+    const names: string[] = [];
+    let match;
+    while ((match = regex.exec(designContent)) !== null) {
+      names.push(match[1].trim());
+    }
+    return names;
+  }
+
+  detectSyncConflicts(deltaSpecs: Array<{ changeName: string; content: string }>): ConflictReport {
+    const reqToChanges = new Map<string, string[]>();
+
+    for (const { changeName, content } of deltaSpecs) {
+      const plan = parseDeltaSpec(content);
+      const names: string[] = [
+        ...plan.modified.map(b => normalizeRequirementName(b.name)),
+        ...plan.renamed.map(r => normalizeRequirementName(r.to)),
+      ];
+      for (const name of names) {
+        const existing = reqToChanges.get(name) || [];
+        existing.push(changeName);
+        reqToChanges.set(name, existing);
+      }
+    }
+
+    const conflicts: SyncConflict[] = [];
+    for (const [requirement, changes] of reqToChanges) {
+      if (changes.length >= 2) {
+        conflicts.push({ requirement, spec: requirement, changes });
+      }
+    }
+
+    return { hasConflicts: conflicts.length > 0, conflicts };
+  }
+
+  isValid(report: ValidationReport): boolean {
+    return report.valid;
+  }
+}

package/templates/abandonment-summary.md

@@ -0,0 +1,29 @@
+# Abandonment Summary
+
+## Change
+
+- **Name**: [change name]
+- **Original goal**: [one sentence]
+
+## Reason
+
+[At least 50 characters explaining why this change was abandoned]
+
+## What Was Tried
+
+- [Action 1 and its outcome]
+- [Action 2 and its outcome]
+
+## Lessons Learned
+
+- [Concrete insight 1 that may help future attempts]
+
+## Recommendations
+
+- [Suggested next step or alternative approach]
+
+## Preserved Work
+
+- [ ] No work preserved (all changes discarded)
+- [ ] Partial work preserved:
+  - Commit `[hash]`: [description]

package/templates/design.md

@@ -0,0 +1,37 @@
+# 技术设计
+
+## 上下文
+
+- 当前状态：
+- 约束条件：
+- 利益相关者：
+
+## 目标
+
+- 本设计必须达成什么
+
+## 非目标
+
+- 本设计刻意不解决什么
+
+## 决策
+
+### 决策 1
+
+- **选择**：
+- **理由**：
+- **考虑的替代方案**：
+
+## 风险与权衡
+
+- 风险 → 缓解措施
+
+## 迁移计划
+
+- 上线步骤：
+- 回滚步骤：
+
+## 待明确问题
+
+- 问题：
+- 决策负责人：