@chongyan/autospec 1.0.1

package/plugins/hooks/scope-sentinel.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec PreToolUse Hook: Scope Sentinel
+ *
+ * During implementation stage (Stage 03), monitors Write/Edit operations
+ * to detect scope creep — modifying files outside the planned scope.
+ *
+ * Detection strategy:
+ * 1. If .autospec/state.json shows currentStage is 03 (implementation)
+ * 2. Check if the target file path is reasonable for the current task
+ * 3. Warn (not block) if editing framework/config files or unrelated modules
+ *
+ * This hook WARNS but never BLOCKS — it's a cognitive nudge, not a gate.
+ *
+ * 优化点：
+ * 1. 使用共享工具函数
+ * 2. 统一错误处理和日志
+ * 3. 缓存状态避免重复读取
+ */
+
+import { createHookLogger, safeJsonParse, handleHookError, readStdin, findProjectRootAsync, fileExists, globalHookCache } from './lib/hook-logger.js';
+
+const logger = createHookLogger('scope-sentinel');
+const stateCache = globalHookCache; // 使用全局单例缓存
+
+// 缓存键前缀
+const CACHE_KEY_PREFIX = 'scope-check:';
+
+async function main() {
+  let input;
+  try {
+    const rawInput = await readStdin(1000);
+    input = safeJsonParse(rawInput, null, 'hook input');
+
+    if (!input) {
+      logger.debug('Empty or invalid input, skipping');
+      process.exit(0);
+    }
+  } catch (err) {
+    logger.error('Failed to parse input', { error: err.message });
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name;
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    logger.debug('Not a write/edit operation, skipping', { toolName });
+    process.exit(0);
+  }
+
+  const fs = await import('fs');
+  const path = await import('path');
+
+  // Find project root
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = await findProjectRootAsync(cwd);
+
+  if (!projectRoot) {
+    logger.debug('No .autospec directory found, skipping');
+    process.exit(0);
+  }
+
+  const statePath = path.join(projectRoot, '.autospec', 'state.json');
+
+  // Check if we should skip based on cached stage check
+  const stageCacheKey = `${CACHE_KEY_PREFIX}${projectRoot}:stage`;
+  let isImplementationStage = stateCache.get(stageCacheKey);
+
+  if (isImplementationStage === undefined) {
+    isImplementationStage = await checkImplementationStage(statePath, fs);
+    stateCache.set(stageCacheKey, isImplementationStage, 30000); // 30s cache
+    logger.debug('Stage checked', { isImplementationStage });
+  } else {
+    logger.debug('Using cached stage check', { isImplementationStage });
+  }
+
+  if (!isImplementationStage) {
+    process.exit(0);
+  }
+
+  const filePath = (input.tool_input?.file_path || '').replace(/\\/g, '/');
+
+  // Skip autospec internal files (specs, state, metrics — those are expected)
+  if (filePath.includes('.autospec/') || filePath.includes('.claude/')) {
+    logger.debug('Skipping autospec internal file', { filePath });
+    process.exit(0);
+  }
+
+  // Detect potentially risky modifications
+  const warnings = [];
+
+  // 1. Modifying package.json / config files (potential scope creep)
+  const configPatterns = [
+    /package\.json$/,
+    /tsconfig.*\.json$/,
+    /\.eslintrc/,
+    /webpack|vite|rollup.*config/,
+    /docker/i,
+    /\.env/
+  ];
+  for (const pattern of configPatterns) {
+    if (pattern.test(filePath)) {
+      warnings.push(
+        `Modifying config file: ${path.basename(filePath)}. ` +
+        `Verify this change is required by the current task scope.`
+      );
+      logger.info('Config file modification detected', { filePath });
+      break;
+    }
+  }
+
+  // 2. Creating new directories (potential feature creep)
+  if (toolName === 'Write') {
+    const dir = path.dirname(filePath);
+    const relDir = path.relative(cwd, dir).replace(/\\/g, '/');
+    // Count directory depth — creating deeply nested new structures may signal scope creep
+    const parts = relDir.split('/').filter(Boolean);
+    if (parts.length > 4) {
+      warnings.push(
+        `Creating file in deeply nested path (${parts.length} levels). ` +
+        `Check if this aligns with the technical design.`
+      );
+      logger.info('Deep nesting detected', { depth: parts.length, path: relDir });
+    }
+  }
+
+  // Load metrics to track scope warnings count
+  const metricsPath = path.join(projectRoot, '.autospec', 'metrics.json');
+  let metrics;
+  try {
+    metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+  } catch {
+    metrics = { totals: { scopeWarnings: 0 } };
+  }
+
+  if (warnings.length > 0) {
+    if (!metrics.totals.scopeWarnings) metrics.totals.scopeWarnings = 0;
+    metrics.totals.scopeWarnings++;
+
+    try {
+      fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2));
+    } catch (err) {
+      logger.debug('Failed to write metrics', { error: err.message });
+    }
+
+    // Graduated response (CP8 三级偏航提醒)
+    let level = '';
+    const count = metrics.totals.scopeWarnings;
+    if (count <= 2) {
+      level = '(scope check — informational)';
+    } else if (count <= 5) {
+      level = '⚠️ (scope check — repeated, please verify)';
+    } else {
+      level = '🚨 (scope check — frequent deviations detected, review needed)';
+    }
+
+    logger.info('Scope warning generated', { level, warningCount: count });
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext:
+          `[AutoSpec Scope Sentinel] ${level}\n` +
+          warnings.join('\n') + '\n' +
+          `Verify this change is within the scope defined in .autospec/specs/*/design.md`
+      }
+    };
+    process.stdout.write(JSON.stringify(output));
+  }
+
+  process.exit(0);
+}
+
+/**
+ * Check if current stage is implementation (Stage 3)
+ */
+async function checkImplementationStage(statePath, fs) {
+  if (!(await fileExists(statePath))) {
+    return false;
+  }
+
+  try {
+    const content = await fs.promises.readFile(statePath, 'utf-8');
+    const state = safeJsonParse(content, null, 'state.json');
+
+    if (!state) {
+      return false;
+    }
+
+    const stage = String(state.currentStage);
+    return stage === '3' || stage === '03';
+  } catch (err) {
+    logger.debug('Failed to read state', { error: err.message });
+    return false;
+  }
+}
+
+main().catch((err) => {
+  const result = handleHookError('scope-sentinel', err, {
+    eventName: 'PreToolUse'
+  });
+  process.stdout.write(JSON.stringify(result.hookSpecificOutput));
+  process.exit(0);
+});

package/plugins/hooks/trace-initialization.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec PreToolUse Hook: Trace Init
+ *
+ * 流程启动时初始化 Trace ID
+ * - 检测到新流程启动（state.json 创建或重置）时生成 traceId
+ * - 记录用户输入用于调试和评测
+ * - 优先级：200（最高）
+ */
+
+import { createHookLogger, safeJsonParse, handleHookError, readStdin, findProjectRootAsync } from './lib/hook-logger.js';
+import { getState, updateState } from './lib/hook-state-manager.js';
+import { generateTraceId, getTraceId, appendTraceEvent } from './lib/trace-context.js';
+import fs from 'fs';
+import path from 'path';
+
+const logger = createHookLogger('trace-initialization');
+
+/**
+ * 检测是否为新流程启动
+ * @param {Object} input - Hook 输入
+ * @param {string} projectRoot - 项目根目录
+ * @returns {boolean} 是否为新流程
+ */
+function isNewPipelineStart(input, projectRoot) {
+  const filePath = input.tool_input?.file_path || '';
+
+  // 检测 state.json 创建
+  if (filePath.includes('state.json')) {
+    const statePath = path.join(projectRoot, '.autospec', 'runtime', 'state.json');
+
+    // 如果 state.json 不存在，说明是新流程
+    if (!fs.existsSync(statePath)) {
+      return true;
+    }
+
+    // 如果正在重置 state.json（写入新的 taskName），也是新流程
+    const content = input.tool_input?.content || '';
+    if (content && (content.includes('"taskName"') || content.includes('"currentStage": "01"'))) {
+      // 检查现有 state 是否有 traceId
+      const existingState = getState(projectRoot);
+      if (!existingState?.traceId) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 检测是否为流程结束
+ * @param {Object} input - Hook 输入
+ * @param {string} projectRoot - 项目根目录
+ * @returns {boolean} 是否为流程结束
+ */
+function isPipelineEnd(input, projectRoot) {
+  const filePath = input.tool_input?.file_path || '';
+
+  // 检测归档操作
+  if (filePath.includes('archives/') && filePath.includes('state.json')) {
+    return true;
+  }
+
+  return false;
+}
+
+async function main() {
+  let input;
+  try {
+    const rawInput = await readStdin(1000);
+    input = safeJsonParse(rawInput, null, 'hook input');
+
+    if (!input) {
+      logger.debug('Empty or invalid input, skipping');
+      process.exit(0);
+    }
+  } catch (err) {
+    logger.error('Failed to parse input', { error: err.message });
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name;
+
+  // 只处理 Write 操作
+  if (toolName !== 'Write') {
+    process.exit(0);
+  }
+
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = await findProjectRootAsync(cwd);
+
+  if (!projectRoot) {
+    logger.debug('No .autospec directory found, skipping');
+    process.exit(0);
+  }
+
+  // 检测新流程启动
+  if (isNewPipelineStart(input, projectRoot)) {
+    const traceId = generateTraceId();
+    logger.info('New pipeline detected, initializing Trace ID', { traceId });
+
+    // 提取用户输入（从 state.json 内容中）
+    const content = input.tool_input?.content || '';
+    let userInput = '';
+    try {
+      const stateData = JSON.parse(content);
+      userInput = stateData.taskName || stateData.userInput || '';
+    } catch (e) {
+      // 忽略解析错误
+    }
+
+    // 增强：记录用户输入到 trace 日志
+    if (userInput) {
+      const traceEvent = {
+        eventId: `init-${Date.now()}`,
+        traceId,
+        timestamp: new Date().toISOString(),
+        type: 'pipeline_started',
+        source: 'trace-initialization',
+        data: {
+          userInput,
+          workflow: input.tool_input?.content?.includes('"workflow"')
+            ? JSON.parse(input.tool_input.content).workflow
+            : 'unknown'
+        }
+      };
+      appendTraceEvent(projectRoot, traceEvent);
+      logger.info('User input recorded', { userInput: userInput.substring(0, 100) });
+    }
+
+    // 不在这里更新 state.json，因为 Write 操作还未完成
+    // 而是输出提示，让后续的 execution-tracker 来处理
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: `[trace-initialization] 新流程启动，Trace ID: ${traceId}，用户输入: ${userInput.substring(0, 50)}...`
+      }
+    }));
+    process.exit(0);
+  }
+
+  // 检测流程结束
+  if (isPipelineEnd(input, projectRoot)) {
+    const traceId = getTraceId(projectRoot);
+    if (traceId) {
+      logger.info('Pipeline ending, archiving Trace', { traceId });
+
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: `[trace-initialization] 流程结束，Trace ID: ${traceId} 正在归档。`
+        }
+      }));
+    }
+    process.exit(0);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const result = handleHookError('trace-initialization', err, {
+    eventName: 'PreToolUse'
+  });
+  process.stdout.write(JSON.stringify(result.hookSpecificOutput));
+  process.exit(0);
+});

package/plugins/memory/templates/code-quality.yaml

@@ -0,0 +1,149 @@
+# AutoSpec Memory Template - Code Quality
+# 代码质量评测记忆模板
+# 复制到 .autospec/autospec:memory/discovered/ 后按需调整
+
+version: "1.0"
+memory:
+  id: "template-code-quality"
+  name: "代码质量评测模板"
+  description: "通用的代码质量评测规则模板"
+  category: "code-quality"
+
+  # 适用条件
+  applicability:
+    tech_stacks: ["*"]  # 适用于所有技术栈
+    file_patterns: ["*"]
+    min_confidence: 0.7
+
+  # 评测规则集合
+  rules:
+    # 规则1: 代码复杂度
+    - id: "complexity-check"
+      name: "代码复杂度检查"
+      description: "检测高复杂度函数和类"
+      severity: "warning"
+
+      detection:
+        type: "metric"
+        metrics:
+          - name: "cyclomatic-complexity"
+            threshold: 10
+            message: "圈复杂度过高，建议拆分为小函数"
+          - name: "cognitive-complexity"
+            threshold: 15
+            message: "认知复杂度过高，建议简化逻辑"
+          - name: "function-length"
+            threshold: 50
+            message: "函数过长，建议拆分"
+          - name: "class-length"
+            threshold: 300
+            message: "类过大，建议拆分职责"
+
+      fixes:
+        - type: "suggest"
+          description: "提供重构建议"
+          action: "generate-refactoring-plan"
+
+    # 规则2: 重复代码
+    - id: "duplicate-code"
+      name: "重复代码检测"
+      description: "检测3行以上的重复代码"
+      severity: "warning"
+
+      detection:
+        type: "similarity"
+        min_lines: 3
+        similarity_threshold: 0.8
+
+      fixes:
+        - type: "suggest"
+          description: "建议提取公共函数"
+          action: "extract-common-function"
+
+    # 规则3: 死代码
+    - id: "dead-code"
+      name: "死代码清理"
+      description: "检测未使用的变量、函数、导入"
+      severity: "info"
+
+      detection:
+        type: "static-analysis"
+        checks:
+          - "unused-variables"
+          - "unused-functions"
+          - "unused-imports"
+          - "unreachable-code"
+
+      fixes:
+        - type: "auto"
+          description: "自动移除死代码"
+          action: "remove-dead-code"
+          validation: "compile-pass"
+
+    # 规则4: 命名规范
+    - id: "naming-convention"
+      name: "命名规范检查"
+      description: "检查变量、函数、类命名是否符合规范"
+      severity: "info"
+
+      detection:
+        type: "pattern"
+        patterns:
+          - name: "camelCase"
+            apply_to: ["variable", "function"]
+            regex: "^[a-z][a-zA-Z0-9]*$"
+          - name: "PascalCase"
+            apply_to: ["class", "interface", "type"]
+            regex: "^[A-Z][a-zA-Z0-9]*$"
+          - name: "SCREAMING_SNAKE_CASE"
+            apply_to: ["constant"]
+            regex: "^[A-Z][A-Z0-9_]*$"
+
+      fixes:
+        - type: "auto"
+          description: "自动重命名"
+          action: "rename-symbol"
+          validation: "compile-pass"
+
+    # 规则5: 代码注释
+    - id: "code-comments"
+      name: "代码注释检查"
+      description: "检查公共API是否有文档注释"
+      severity: "info"
+
+      detection:
+        type: "ast-pattern"
+        patterns:
+          - "public-function-without-doc"
+          - "public-class-without-doc"
+          - "complex-logic-without-comment"
+
+      fixes:
+        - type: "suggest"
+          description: "生成文档注释模板"
+          action: "generate-doc-template"
+
+  # 执行配置
+  execution:
+    # 执行顺序
+    order:
+      - "dead-code"        # 先清理死代码
+      - "naming-convention" # 再修复命名
+      - "code-comments"    # 再补注释
+      - "complexity-check" # 最后处理复杂度
+      - "duplicate-code"
+
+    # 执行条件
+    conditions:
+      - "compile-pass"     # 编译通过
+      - "test-pass"        # 测试通过
+
+    # 失败处理
+    on_failure:
+      action: "rollback"    # 失败回滚
+      notify: true          # 通知用户
+
+  # 统计和反馈
+  statistics:
+    track: true             # 追踪执行统计
+    feedback: true          # 收集反馈

package/plugins/memory/templates/multi-system.yaml

@@ -0,0 +1,155 @@
+# AutoSpec Memory Template - Multi-System
+# 多系统项目评测记忆模板
+
+version: "1.0"
+memory:
+  id: "template-multi-system"
+  name: "多系统项目评测模板"
+  description: "针对多系统项目的专项评测"
+  category: "multi-system"
+
+  # 适用条件
+  applicability:
+    project_types: ["multi-system"]
+    min_subsystems: 2
+
+  rules:
+    # 规则1: 接口契约一致性
+    - id: "contract-consistency"
+      name: "接口契约一致性"
+      description: "检查前后端接口契约是否一致"
+      severity: "error"
+
+      detection:
+        type: "contract-analysis"
+        checks:
+          - "api-definition-vs-implementation"
+          - "request-schema-match"
+          - "response-schema-match"
+          - "type-compatibility"
+
+        sources:
+          - "contracts/api.yaml"      # 契约定义
+          - "frontend/src/api/"       # 前端调用
+          - "backend/src/controller/" # 后端实现
+
+      fixes:
+        - type: "suggest"
+          description: "同步接口定义"
+          action: "sync-contract"
+
+    # 规则2: 共享逻辑识别
+    - id: "shared-logic"
+      name: "共享逻辑抽离"
+      description: "识别跨系统重复代码，建议抽离"
+      severity: "warning"
+
+      detection:
+        type: "cross-system-similarity"
+        min_similarity: 0.8
+        min_lines: 10
+
+        scopes:
+          - "data-models"
+          - "utility-functions"
+          - "validation-logic"
+          - "constants"
+
+      fixes:
+        - type: "suggest"
+          description: "建议创建共享库"
+          action: "suggest-shared-library"
+
+    # 规则3: 依赖循环检测
+    - id: "dependency-cycle"
+      name: "依赖循环检测"
+      description: "检测子系统间的循环依赖"
+      severity: "error"
+
+      detection:
+        type: "dependency-graph"
+        algorithm: "tarjan-cycle-detection"
+
+        scope:
+          - "import-statements"
+          - "service-calls"
+          - "event-subscriptions"
+
+      fixes:
+        - type: "suggest"
+          description: "建议解耦方案"
+          action: "suggest-decoupling"
+
+    # 规则4: 构建顺序优化
+    - id: "build-order"
+      name: "构建顺序优化"
+      description: "分析并优化子系统构建顺序"
+      severity: "info"
+
+      detection:
+        type: "build-analysis"
+        analyze:
+          - "current-build-time"
+          - "dependency-graph"
+          - "parallel-opportunities"
+
+      fixes:
+        - type: "suggest"
+          description: "优化构建配置"
+          action: "optimize-build-config"
+
+    # 规则5: 数据模型对齐
+    - id: "data-model-alignment"
+      name: "数据模型对齐"
+      description: "检查跨系统数据模型一致性"
+      severity: "warning"
+
+      detection:
+        type: "schema-comparison"
+        compare:
+          - "backend/entities/" vs "frontend/src/types/"
+          - "backend/dto/" vs "frontend/src/api/types/"
+
+        checks:
+          - "field-name-consistency"
+          - "type-compatibility"
+          - "nullability-match"
+
+      fixes:
+        - type: "suggest"
+          description: "同步数据模型"
+          action: "sync-data-models"
+
+    # 规则6: 错误处理统一
+    - id: "error-handling"
+      name: "错误处理统一"
+      description: "检查跨系统错误处理是否统一"
+      severity: "warning"
+
+      detection:
+        type: "error-pattern-analysis"
+        checks:
+          - "error-code-consistency"
+          - "error-message-format"
+          - "error-response-structure"
+
+      fixes:
+        - type: "suggest"
+          description: "统一错误处理规范"
+          action: "unify-error-handling"
+
+  execution:
+    order:
+      - "dependency-cycle"      # 优先处理架构问题
+      - "contract-consistency"
+      - "data-model-alignment"
+      - "shared-logic"
+      - "error-handling"
+      - "build-order"
+
+    conditions:
+      - "all-subsystems-compile"
+
+    on_failure:
+      action: "report"
+      notify: true