autosnippet 3.2.1 → 3.2.3

package/lib/cli/SetupService.js

@@ -5,7 +5,8 @@
  *
  *   Step 1  .autosnippet/ 运行时目录 + config.json + .gitignore
  *   Step 2  AutoSnippet/ 子仓库（核心数据 + 权限能力 + skills/）
- *   Step 3  IDE 集成（VSCode MCP + Cursor MCP + copilot-instructions + cursor-rules + skills-template）
+ *   Step 3  IDE 集成（VSCode MCP + Cursor MCP + copilot-instructions + cursor-rules
+ *           + skills-template + cursor-workflow + claude-hooks + guard-ci + pre-commit-hook）
  *   Step 4  SQLite 数据库 + V1 数据迁移
  *   Step 5  平台相关初始化（macOS → Xcode Snippets）
  *
@@ -432,24 +433,27 @@ export class SetupService {
   /* ═══ Step 3: IDE 集成 ═══════════════════════════════ */
 
   stepIDE() {
+    const configured = [];
+
+    // MCP 配置（总是写入/合并，不会跳过）
     this._configureVSCodeMCP();
+    configured.push('vscode-mcp');
     this._configureCursorMCP();
-    this._copyCopilotInstructions();
-    this._generateAgentInstructionFiles();
-    this._copyCursorRules();
-    this._copySkillsTemplate();
+    configured.push('cursor-mcp');
+
+    // 模板文件（可能因已存在/用户文件而跳过）
+    if (this._copyCopilotInstructions()) configured.push('copilot-instructions');
+    this._ensureTaskGraphInstructions();
+    if (this._generateAgentInstructionFiles()) configured.push('agent-instructions');
+    if (this._copyCursorRules()) configured.push('cursor-rules');
+    if (this._copySkillsTemplate()) configured.push('skills-template');
+    if (this._copyCursorWorkflow()) configured.push('cursor-workflow');
+    if (this._copyClaudeHooks()) configured.push('claude-hooks');
+    if (this._copyGuardCI()) configured.push('guard-ci');
+    if (this._installPreCommitHook()) configured.push('pre-commit-hook');
     // NOTE: .qoder/ .trae/ 不再自动创建，用户可通过 `asd mirror` 按需生成
 
     const extResult = this._installVSCodeExtension();
-
-    const configured = [
-      'vscode-mcp',
-      'cursor-mcp',
-      'copilot-instructions',
-      'agent-instructions',
-      'cursor-rules',
-      'skills-template',
-    ];
     if (extResult) {
       configured.push(...extResult);
     }
@@ -711,23 +715,79 @@ export class SetupService {
   _copyCopilotInstructions() {
     const src = join(REPO_ROOT, 'templates', 'copilot-instructions.md');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.github');
     const dest = join(destDir, 'copilot-instructions.md');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
     }
 
     // 即使 --force，也不覆盖用户原有的非 AutoSnippet 文件
     const { canWrite } = checkWriteSafety(dest);
     if (!canWrite) {
-      return;
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
+  }
+
+  /** @private TaskGraph 决策记忆激活段落注入 */
+  _ensureTaskGraphInstructions() {
+    const githubDir = join(this.projectRoot, '.github');
+    const filePath = join(githubDir, 'copilot-instructions.md');
+
+    // 使用 HTML 注释标记界定段落，避免标题被编辑后重复追加（D3）
+    const BEGIN_MARKER = '<!-- autosnippet:begin -->';
+    const END_MARKER = '<!-- autosnippet:end -->';
+
+    const autosnippetSection = `
+${BEGIN_MARKER}
+## AutoSnippet
+
+This project uses AutoSnippet for knowledge management and decision tracking.
+In VS Code Agent Mode, type \`#asd\` before your message to activate project memory.
+
+### ⚠️ MANDATORY — Call \`autosnippet_ready\` FIRST
+
+Before doing ANY work, you MUST call \`autosnippet_ready()\` at the start of every conversation.
+This loads **active team decisions** and **pending tasks** that you must respect.
+Skipping this step will cause you to contradict team agreements.
+
+\`\`\`
+autosnippet_ready()           → Load decisions + context (ALWAYS FIRST)
+autosnippet_decide(record)    → Save new team agreement
+autosnippet_task(create/close) → Task lifecycle
+\`\`\`
+${END_MARKER}
+`;
+
+    if (!existsSync(githubDir)) {
+      mkdirSync(githubDir, { recursive: true });
+    }
+
+    if (existsSync(filePath)) {
+      const existing = readFileSync(filePath, 'utf8');
+      // 通过 HTML 注释标记检测，不依赖可编辑的标题文本
+      if (existing.includes(BEGIN_MARKER)) {
+        // 替换现有段落（支持升级）
+        const updated = existing.replace(
+          new RegExp(`${BEGIN_MARKER}[\\s\\S]*?${END_MARKER}`),
+          autosnippetSection.trim()
+        );
+        writeFileSync(filePath, updated);
+        return { action: 'updated' };
+      }
+      // 追加到末尾
+      writeFileSync(filePath, existing + '\n' + autosnippetSection);
+      return { action: 'appended' };
+    }
+
+    writeFileSync(filePath, autosnippetSection.trimStart());
+    return { action: 'created' };
   }
 
   /**
@@ -737,6 +797,7 @@ export class SetupService {
    */
   _generateAgentInstructionFiles() {
     const projectName = this.projectRoot.split('/').pop();
+    let wrote = false;
 
     // AGENTS.md
     const agentsPath = join(this.projectRoot, 'AGENTS.md');
@@ -746,31 +807,35 @@ export class SetupService {
         const agentsContent = [
           `# ${projectName} — Agent Instructions`,
           '',
-          '> Auto-generated by AutoSnippet. Will be enriched after `asd bootstrap`.',
+          '> Auto-generated by AutoSnippet.',
           '',
-          '## Project Knowledge Base',
+          '## AutoSnippet Integration',
           '',
-          'This project uses **AutoSnippet** for knowledge management.',
-          'Run `asd bootstrap` to populate the knowledge base, then this file will be',
-          'regenerated with coding standards, patterns, and tool references.',
+          'This project uses **AutoSnippet** for knowledge management and decision tracking.',
           '',
-          '## MCP Tools',
+          '### MCP Tools',
           '',
-          'Use these MCP tools to access the full knowledge base:',
-          '- `autosnippet_search` — Search knowledge (mode: auto/context/keyword/semantic)',
-          '- `autosnippet_knowledge` — Browse/get recipes (operation: list/get/insights)',
-          '- `autosnippet_submit_knowledge` — Submit candidate (strict validation)',
+          '- `autosnippet_search` — Search knowledge',
+          '- `autosnippet_knowledge` — Browse/get recipes',
+          '- `autosnippet_submit_knowledge` — Submit candidate',
           '- `autosnippet_guard` — Code compliance check',
           '- `autosnippet_health` — Service health & KB stats',
+          '- `autosnippet_ready` — Session entry point (loads decisions + tasks)',
+          '- `autosnippet_decide` — Decision management (record/revise/unpin)',
+          '- `autosnippet_task` — Task CRUD (create/claim/close/fail/defer)',
           '',
-          '## Mandatory Constraints',
+          '### VS Code Agent Mode',
           '',
-          '1. **Do NOT modify** knowledge base files directly (`AutoSnippet/`, `.autosnippet/`).',
-          '2. Create or update knowledge **only** through MCP tools.',
-          '3. **Prefer Recipes** as project standards; source code is supplementary.',
+          'Type `#asd` before your message in Agent Mode to activate project memory.',
+          '',
+          '### Constraints',
+          '',
+          '1. Do NOT modify knowledge base files directly.',
+          '2. Create or update knowledge only through MCP tools.',
           '',
         ].join('\n');
         writeFileSync(agentsPath, agentsContent);
+        wrote = true;
       } else {
       }
     }
@@ -783,64 +848,198 @@ export class SetupService {
         const claudeContent = [
           `# ${projectName} — Claude Code Instructions`,
           '',
-          '> Auto-generated by AutoSnippet. Will be enriched after `asd bootstrap`.',
+          '> Auto-generated by AutoSnippet.',
+          '',
+          '## AutoSnippet Integration',
           '',
-          '## MCP Integration',
+          'This project uses AutoSnippet for knowledge management and decision tracking.',
           '',
-          'This project has an AutoSnippet MCP server configured.',
-          'Use the following tools to access project knowledge:',
-          '- `autosnippet_search` — Search knowledge (mode: auto/context/keyword/semantic)',
-          '- `autosnippet_knowledge` — Browse/get recipes (operation: list/get/insights)',
-          '- `autosnippet_submit_knowledge` — Submit candidate (strict validation)',
+          '### MCP Tools',
+          '',
+          '- `autosnippet_search` — Search knowledge',
+          '- `autosnippet_knowledge` — Browse/get recipes',
+          '- `autosnippet_submit_knowledge` — Submit candidate',
           '- `autosnippet_guard` — Code compliance check',
           '- `autosnippet_health` — Service health & KB stats',
+          '- `autosnippet_ready` — Session entry point (loads decisions + tasks)',
+          '- `autosnippet_decide` — Decision management (record/revise/unpin)',
+          '- `autosnippet_task` — Task CRUD (create/claim/close/fail/defer)',
+          '',
+          '### Claude + VS Code',
+          '',
+          'Claude Code uses MCP tools directly. Run `asd server` to start the API server.',
+          'In VS Code Agent Mode, type `#asd` before your message to activate project memory.',
           '',
-          '## Mandatory Constraints',
+          '### Constraints',
           '',
-          '1. **Do NOT modify** knowledge base files directly (`AutoSnippet/`, `.autosnippet/`).',
-          '2. Create or update knowledge **only** through MCP tools.',
-          '3. **Prefer Recipes** as project standards; source code is supplementary.',
+          '1. Do NOT modify knowledge base files directly.',
+          '2. Create or update knowledge only through MCP tools.',
           '',
         ].join('\n');
         writeFileSync(claudePath, claudeContent);
+        wrote = true;
       } else {
       }
     }
+    return wrote;
   }
 
   /** @private .cursor/rules/autosnippet-conventions.mdc */
   _copyCursorRules() {
     const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-conventions.mdc');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.cursor', 'rules');
     const dest = join(destDir, 'autosnippet-conventions.mdc');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
   }
 
   /** @private .cursor/rules/autosnippet-skills.mdc — Project Skills 索引模板 */
   _copySkillsTemplate() {
     const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-skills.mdc');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.cursor', 'rules');
     const dest = join(destDir, 'autosnippet-skills.mdc');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
   }
+  /** @private .cursor/rules/autosnippet-workflow.mdc — TaskGraph & Guard 工作流 */
+  _copyCursorWorkflow() {
+    const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-workflow.mdc');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const destDir = join(this.projectRoot, '.cursor', 'rules');
+    const dest = join(destDir, 'autosnippet-workflow.mdc');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+
+  /**
+   * @private .claude/hooks.yaml — Claude Code SessionStart hook
+   * 会话开始时自动 prime TaskGraph 上下文
+   */
+  _copyClaudeHooks() {
+    const src = join(REPO_ROOT, 'templates', 'claude-hooks.yaml');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const claudeDir = join(this.projectRoot, '.claude');
+    const dest = join(claudeDir, 'hooks.yaml');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    // 即使 --force，也不覆盖用户自己的 hooks 文件
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
+    }
+
+    mkdirSync(claudeDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+
+  /**
+   * @private .github/workflows/autosnippet-guard.yml — Guard CI/CD workflow
+   * 在 push/PR 时自动运行 Guard 合规检查
+   */
+  _copyGuardCI() {
+    const src = join(REPO_ROOT, 'templates', 'guard-ci.yml');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const destDir = join(this.projectRoot, '.github', 'workflows');
+    const dest = join(destDir, 'autosnippet-guard.yml');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
+    }
+
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+
+  /**
+   * @private .git/hooks/pre-commit — Guard pre-commit hook
+   * 如果项目使用 husky，则安装到 .husky/pre-commit
+   * 否则安装到 .git/hooks/pre-commit
+   * 已存在 pre-commit hook 时不覆盖（避免破坏用户现有 hook）
+   */
+  _installPreCommitHook() {
+    const src = join(REPO_ROOT, 'templates', 'pre-commit-guard.sh');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    // 优先检查 husky
+    const huskyDir = join(this.projectRoot, '.husky');
+    const gitHooksDir = join(this.projectRoot, '.git', 'hooks');
+
+    let dest;
+    if (existsSync(huskyDir)) {
+      // 项目使用 husky — 安装到 .husky/pre-commit
+      dest = join(huskyDir, 'pre-commit');
+    } else if (existsSync(join(this.projectRoot, '.git'))) {
+      // 普通 git 项目 — 安装到 .git/hooks/pre-commit
+      dest = join(gitHooksDir, 'pre-commit');
+      mkdirSync(gitHooksDir, { recursive: true });
+    } else {
+      // 非 git 项目，跳过
+      return false;
+    }
+
+    // 已存在 pre-commit hook 时不覆盖（可能是用户自己的 hook）
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    // 即使 --force，也不覆盖用户自己的 pre-commit hook
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
+    }
+
+    copyFileSync(src, dest);
+    // 确保可执行
+    try {
+      execSync(`chmod +x "${dest}"`, { stdio: 'pipe' });
+    } catch {
+      /* Windows 不需要 chmod */
+    }
+    return true;
+  }
+
   /** @private 镜像 .cursor/rules/ 中的 autosnippet-* 文件到目标 IDE 目录（Qoder / Trae 兼容）
    *  只复制 autosnippet- 前缀的文件，不触碰用户自己创建的规则 */
   _mirrorCursorToIDE(targetDirName) {

package/lib/domain/knowledge/KnowledgeEntry.js

@@ -203,10 +203,21 @@ export class KnowledgeEntry {
     return [...regexRules, ...astRules];
   }
 
+  /* ═══ 系统标签 ═══════════════════════════════════ */
+
+  /** 系统内部标签前缀 — 内部元数据，不应暴露给最终用户 */
+  static SYSTEM_TAG_PREFIXES = ['dimension:', 'bootstrap:', 'internal:', 'system:'];
+
+  /** 判断是否为系统内部标签 */
+  static isSystemTag(tag) {
+    return KnowledgeEntry.SYSTEM_TAG_PREFIXES.some((p) => tag.startsWith(p));
+  }
+
   /* ═══ 序列化 ═══════════════════════════════════════ */
 
   /**
    * Domain → JSON (camelCase 直出，全链路统一)
+   * 注意: tags 保留原始值（含系统标签），对外 API 使用 sanitizeForAPI() 过滤
    */
   toJSON() {
     return {

package/lib/domain/task/Task.js

@@ -60,12 +60,18 @@ export class Task {
     if (this.status === 'closed') {
       throw new Error('Cannot claim a closed task');
     }
+    if (this.status === 'pinned') {
+      throw new Error('Cannot claim a pinned decision. Use unpin_decision or revise_decision instead.');
+    }
     this.status = 'in_progress';
     this.assignee = assignee;
     this.updatedAt = Math.floor(Date.now() / 1000);
   }
 
   close(reason = 'Completed') {
+    if (this.status === 'pinned') {
+      throw new Error('Cannot close a pinned decision directly. Use unpin_decision or revise_decision instead.');
+    }
     this.status = 'closed';
     this.closeReason = reason;
     this.closedAt = Math.floor(Date.now() / 1000);
@@ -79,7 +85,28 @@ export class Task {
     this.updatedAt = Math.floor(Date.now() / 1000);
   }
 
+  pin() {
+    if (this.status === 'closed') {
+      throw new Error('Cannot pin a closed task');
+    }
+    this.status = 'pinned';
+    this.updatedAt = Math.floor(Date.now() / 1000);
+  }
+
+  unpin(reason = '') {
+    if (this.status !== 'pinned') {
+      throw new Error('Can only unpin a pinned task');
+    }
+    this.status = 'closed';
+    this.closeReason = reason || 'Unpinned by user';
+    this.closedAt = Math.floor(Date.now() / 1000);
+    this.updatedAt = this.closedAt;
+  }
+
   defer(reason = '') {
+    if (this.status === 'pinned') {
+      throw new Error('Cannot defer a pinned decision. Use unpin_decision or revise_decision instead.');
+    }
     this.status = 'deferred';
     if (reason) {
       this.notes = `[deferred] ${reason}`;
@@ -91,6 +118,9 @@ export class Task {
     if (this.status === 'closed') {
       throw new Error('Cannot fail a closed task');
     }
+    if (this.status === 'pinned') {
+      throw new Error('Cannot fail a pinned decision. Use unpin_decision or revise_decision instead.');
+    }
     this.status = 'open';
     this.failCount += 1;
     this.lastFailReason = reason || 'Unknown failure';
@@ -120,11 +150,11 @@ export class Task {
     if (typeof this.priority !== 'number' || !Number.isInteger(this.priority) || this.priority < 0 || this.priority > 4) {
       throw new Error(`priority must be an integer between 0 and 4 (got ${this.priority})`);
     }
-    const validStatuses = ['open', 'in_progress', 'deferred', 'closed'];
+    const validStatuses = ['open', 'in_progress', 'deferred', 'closed', 'pinned'];
     if (!validStatuses.includes(this.status)) {
       throw new Error(`invalid status: ${this.status}`);
     }
-    const validTypes = ['epic', 'task', 'bug', 'chore'];
+    const validTypes = ['epic', 'task', 'bug', 'chore', 'decision'];
     if (!validTypes.includes(this.taskType)) {
       throw new Error(`invalid task type: ${this.taskType}`);
     }

package/lib/domain/task/TaskDependency.js

@@ -19,6 +19,7 @@ export const DepType = Object.freeze({
   DISCOVERED_FROM: 'discovered-from',
   RELATED: 'related',
   KNOWLEDGE_REF: 'knowledge-ref', // AutoSnippet 独有：关联知识条目
+  SUPERSEDES: 'supersedes',       // 决策演化链：新决策取代旧决策
 });
 
 /** 所有合法的依赖类型值列表 */