@double-codeing/flow2spec 3.1.1 → 3.1.2

package/README.en.md

@@ -151,7 +151,7 @@ natural language: implement the proposal above         ← AI starts coding (tas
 | `/f2s-kb-feat` | Add a new capability |
 | `/f2s-kb-fix` | Fix a bug |
 | `/f2s-kb-sync` | Sync knowledge base |
-| `/f2s-git-commit` | Commit code |
+| `/f2s-git-commit` | Commit code; "quick commit" skips KB coverage check |
 | `/f2s-kb-add <path>` | Import API module into knowledge base |
 
 For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
@@ -186,4 +186,4 @@ For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Comma
 
 ## License
 
-MIT. Copyright © 2026 兰涛
+MIT. Copyright © 2026 兰涛

package/docs/en/directory-conventions.md

@@ -65,6 +65,10 @@ Type meanings:
 | `config` | Configuration items, switches, defaults, initialization parameters |
 | `policy` | Process, rule, constraint, gate, prohibition, agent orchestration, skill step |
 
+## Topic Granularity
+
+A topic is a routing summary plus key boundaries; details belong in `stock-docs/`. Consider splitting into a main topic plus independently matchable sub-topics when its stock-doc exceeds 300-500 lines, matcher `includeAny` exceeds 12 terms, or the body spans more than 3 unrelated responsibility areas.
+
 ---
 
 ## Related Documents

package/docs/en/usage-guide.md

@@ -116,6 +116,8 @@ After `flow2spec init codex`, Codex projects include `.codex/hooks.json` and `.c
 
 After `flow2spec init cursor`, Cursor projects include `.cursor/hooks.json` and `.cursor/hooks/f2s-update-check.js`. The hook runs on Cursor `sessionStart` and injects upgrade reminders through `additional_context`. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip the check.
 
+After `flow2spec init claude`, Claude projects include `.claude/settings.json` and `.claude/hooks/f2s-update-check.js`. All three integrations now use a single SessionStart hook. The script injects an agent-instruction notice through `additional_context`, requiring the agent to relay the message verbatim to the user. The notice format is: "Current project `<project>` knowledge-base version v<current>, lower than latest package version v<latest>. Run the f2s-kb-upgrade skill to align templates and routing." If today's cache still flags a needed upgrade, every new session re-injects the reminder; after a successful upgrade, `f2s-kb-upgrade` clears `.Knowledge/update-check.json` so stale reminders disappear.
+
 ---
 
 ## 4. Agent Execution Configuration

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -120,6 +120,8 @@ Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json` 与 `
 
 Cursor 项目执行 `flow2spec init cursor` 后会写入 `.cursor/hooks.json` 与 `.cursor/hooks/f2s-update-check.js`，在 Cursor `sessionStart` 自动检查知识库版本；脚本通过 `additional_context` 把升级提示注入会话。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。
 
+Claude 项目执行 `flow2spec init claude` 后会写入 `.claude/settings.json` 与 `.claude/hooks/f2s-update-check.js`，在 Claude `SessionStart` 自动检查知识库版本——三端均为单脚本架构。脚本通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户），格式为："当前项目「<项目名>」知识库版本 v<当前版本>，低于最新包版本 v<最新版本>。可执行 f2s-kb-upgrade skill 对齐模板与路由。"若当天缓存仍标记需升级，新会话每次都会重新注入提示；升级成功后 `f2s-kb-upgrade` 会清理 `.Knowledge/update-check.json`，避免旧提示残留。
+
 ---
 
 ## 四、Agent 执行配置

package/docs//347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md

@@ -65,6 +65,10 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 | `config` | 配置项、开关、默认值、初始化参数 |
 | `policy` | 流程、规则、约束、门禁、禁止项、agent 编排、技能步骤 |
 
+## 主题粒度
+
+topic 是路由摘要与关键边界，细节放在 `stock-docs/`。若对应 stock-doc 超过 300–500 行、matcher `includeAny` 超过 12 个，或正文出现 3 个以上不相干职责域，建议拆成主 topic + 可独立命中的子 topic。
+
 ---
 
 ## 相关文档

package/docs//350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -191,7 +191,9 @@ flowchart LR
     J -- 是 --> Z
     J -- 否 --> K{.Knowledge/update-check.json 今天已检查?}
 
-    K -- 是 --> Z
+    K -- 是 --> K1{缓存显示需升级?}
+    K1 -- 否 --> Z
+    K1 -- 是 --> Q
     K -- 否 --> L[读取 .Knowledge/manifest-routing.json version]
 
     L --> M{有 manifest version?}

package/lib/claudeSettingsAdapter.js

@@ -26,6 +26,22 @@ function hasHookCommand(arr, fragment) {
   return false;
 }
 
+function removeHookCommand(arr, fragment) {
+  if (!Array.isArray(arr)) return [];
+  const next = [];
+  for (const group of arr) {
+    if (!group || !Array.isArray(group.hooks)) {
+      next.push(group);
+      continue;
+    }
+    const hooks = group.hooks.filter((h) => {
+      return !(h && h.type === 'command' && String(h.command || '').includes(fragment));
+    });
+    if (hooks.length) next.push(Object.assign({}, group, { hooks }));
+  }
+  return next;
+}
+
 // 旧函数名保持兼容
 function hasF2sHook(preToolUseArr) {
   return hasHookCommand(preToolUseArr, 'f2s-config-inject');
@@ -75,7 +91,9 @@ function mergeConfigSessionHook(existing) {
 }
 
 /**
- * 将 f2s SessionStart（版本检查）hook 合并进 settings。
+ * 将 f2s 更新检查 hook 合并进 settings：
+ * - SessionStart：执行完整检测，写入 .Knowledge/update-check.json，并直接 emit 提示
+ * - 同时清理旧版 UserPromptSubmit 中的 f2s-update-check / f2s-update-notice
  * @param {object} existing
  * @returns {{ settings, changed }}
  */
@@ -84,15 +102,26 @@ function mergeUpdateCheckHook(existing) {
   if (!next.hooks) next.hooks = {};
   if (!next.hooks.SessionStart) next.hooks.SessionStart = [];
 
-  if (hasHookCommand(next.hooks.SessionStart, 'f2s-update-check')) {
-    return { settings: next, changed: false };
+  let changed = false;
+
+  if (Array.isArray(next.hooks.UserPromptSubmit)) {
+    const before = JSON.stringify(next.hooks.UserPromptSubmit);
+    next.hooks.UserPromptSubmit = removeHookCommand(next.hooks.UserPromptSubmit, 'f2s-update-check');
+    next.hooks.UserPromptSubmit = removeHookCommand(next.hooks.UserPromptSubmit, 'f2s-update-notice');
+    if (JSON.stringify(next.hooks.UserPromptSubmit) !== before) changed = true;
+    if (next.hooks.UserPromptSubmit.length === 0) {
+      delete next.hooks.UserPromptSubmit;
+    }
   }
 
-  next.hooks.SessionStart.push({
-    hooks: [{ type: 'command', command: HOOK_COMMAND_UPDATE_CHECK }],
-  });
+  if (!hasHookCommand(next.hooks.SessionStart, 'f2s-update-check')) {
+    next.hooks.SessionStart.push({
+      hooks: [{ type: 'command', command: HOOK_COMMAND_UPDATE_CHECK }],
+    });
+    changed = true;
+  }
 
-  return { settings: next, changed: true };
+  return { settings: next, changed };
 }
 
 /**
@@ -145,7 +174,7 @@ function copyHookScript(claudeRoot, templatesDir, scriptName) {
 }
 
 /**
- * 主入口：为 claude agent 配置 f2s hooks（SessionStart 配置摘要 + PreToolUse 守门 + SessionStart 更新检查）。
+ * 主入口：为 claude agent 配置 f2s hooks（SessionStart 配置摘要 + PreToolUse 守门 + 更新检测/提示）。
  * @param {string} cwd
  * @param {string} templatesDir
  * @returns {{ hookScriptResult, updateCheckResult, settingsChanged }}
@@ -158,6 +187,12 @@ function writeClaudeAgentHooks(cwd, templatesDir) {
   const configSessionResult = copyHookScript(claudeRoot, templatesDir, 'f2s-config-session.js');
   const updateCheckResult = copyHookScript(claudeRoot, templatesDir, 'f2s-update-check.js');
 
+  // 清理旧版残留的 f2s-update-notice.js
+  const noticeStale = path.join(claudeRoot, 'hooks', 'f2s-update-notice.js');
+  if (fs.existsSync(noticeStale)) {
+    try { fs.unlinkSync(noticeStale); } catch (_) {}
+  }
+
   let settings = readSettings(claudeRoot);
   let changed = false;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

package/templates/AGENTS.md

@@ -100,7 +100,7 @@ Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionSt
 **规则层双保险**（若 hook 未运行，则按本节补检；与脚本缓存互为备份）：
 
 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。
-2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），**跳过，不执行脚本，不做任何提示**。
+2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。
 3. 上述两步均未跳过时：执行 `node .codex/hooks/f2s-update-check.js`，解析标准输出的 JSON：
    - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `/f2s-kb-upgrade`）。
    - 无输出或解析失败：静默，不提示。

package/templates/hooks/f2s-update-check.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 /**
- * flow2spec UserPromptSubmit hook — 每天第一次对话时检查版本更新。
+ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。
  * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本：
  *   - 一致或本地更新 → 静默退出
  *   - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade）
- * 已检查过（24h 内）则完全静默，不做任何输出。
+ * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。
  * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。
  */
 const fs   = require('fs');
@@ -32,16 +32,58 @@ function readCache() {
   } catch (_) { return null; }
 }
 
+function getProjectName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+    if (pkg && pkg.name) return String(pkg.name);
+  } catch (_) {}
+  return path.basename(process.cwd());
+}
+
+function buildNotice(latestNpm, manifestVersion) {
+  const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`;
+  return [
+    `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`,
+    ``,
+    userMsg,
+  ].join('\n');
+}
+
+function emitNotice(notice) {
+  process.stdout.write(
+    JSON.stringify({
+      additional_context: notice,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: notice,
+      },
+    }) + '\n'
+  );
+}
+
 function writeCache(latestNpm, manifestVersion) {
   try {
+    const needsUpgrade = cmpVer(manifestVersion, latestNpm) < 0;
     fs.writeFileSync(
       CACHE_FILE,
-      `${JSON.stringify({ latestNpm, manifestVersion, checkedAt: Date.now() }, null, 2)}\n`,
+      `${JSON.stringify({
+        latestNpm,
+        manifestVersion,
+        needsUpgrade,
+        notice: needsUpgrade ? buildNotice(latestNpm, manifestVersion) : '',
+        checkedAt: Date.now(),
+      }, null, 2)}\n`,
       'utf8'
     );
   } catch (_) {}
 }
 
+function deleteCache() {
+  try {
+    if (fs.existsSync(CACHE_FILE)) fs.unlinkSync(CACHE_FILE);
+  } catch (_) {}
+}
+
 // ── 版本比较 ─────────────────────────────────────────────────────────────────
 
 function parseVer(v) {
@@ -103,7 +145,24 @@ function isEnabled() {
 function main() {
   if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) return;
   if (!isEnabled()) return;
-  if (readCache()) return;  // 今天已检查过，静默退出
+  const cache = readCache();
+  if (cache) {
+    // 今天已检查过则不重复查 npm；若缓存显示仍需升级，每个新会话继续提醒。
+    const needsUpgrade = cache.needsUpgrade === true ||
+      cmpVer(cache.manifestVersion, cache.latestNpm) < 0;
+    if (needsUpgrade) {
+      const currentManifestVersion = getManifestVersion();
+      if (currentManifestVersion && cache.latestNpm &&
+          cmpVer(currentManifestVersion, cache.latestNpm) >= 0) {
+        deleteCache();
+        return;
+      }
+      // SessionStart 进入新会话：缓存命中且仍需升级，直接 emit。
+      const notice = buildNotice(cache.latestNpm, cache.manifestVersion);
+      emitNotice(notice);
+    }
+    return;
+  }
 
   const manifestVersion = getManifestVersion();
   if (!manifestVersion) return;  // 无知识库，跳过
@@ -121,21 +180,8 @@ function main() {
 
   if (cmpVer(manifestVersion, latestNpm) >= 0) return;  // 已是最新
 
-  // 知识库落后于 npm 最新版，注入提示
-  const notice = [
-    `[flow2spec] 知识库版本 v${manifestVersion} 低于最新包版本 v${latestNpm}。`,
-    `建议在此对话中执行 f2s-kb-upgrade 升级知识库模板与路由结构。`,
-  ].join(' ');
-
-  process.stdout.write(
-    JSON.stringify({
-      additional_context: notice,
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext: notice,
-      },
-    }) + '\n'
-  );
+  const notice = buildNotice(latestNpm, manifestVersion);
+  emitNotice(notice);
 }
 
 main();

package/templates/rules/f2s-flow2spec-unified-entry.mdc

@@ -89,16 +89,16 @@ alwaysApply: true
 
 **例外（应显式否定）**：A、B 两种做法在逻辑上均正确，但项目已做出**排他性选择**时，须写出「不用 B」——不说清楚，读者无法判断 B 是否仍可选。
 
-## 知识库版本自检（sessionStart 自动触发；每日首次，仅 updateCheck.enabled=true 时）
+## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时）
 
-Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`**，在 `sessionStart` 自动执行 `node .cursor/hooks/f2s-update-check.js`；脚本通过 `additional_context` 把升级提示注入会话。Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件自动执行 `node .codex/hooks/f2s-update-check.js`。
+三端均采用 **SessionStart 单脚本**架构：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`** 在 `SessionStart` 的 `startup|resume` 事件执行 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`** 在 `SessionStart` 执行 `node .claude/hooks/f2s-update-check.js`。脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。
 
 **规则层双保险**（与脚本缓存互为备份）：
 
 1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。
-2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），**跳过，不执行脚本，不做任何提示**。
-3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON：
-   - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `/f2s-kb-upgrade`）。
+2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。
+3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON：
+   - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。
    - 无输出或解析失败：静默，不提示。
 4. 以上步骤出现任何错误，静默跳过，不影响正常对话。
 

package/templates/skills/f2s-kb-upgrade/SKILL.md

@@ -182,6 +182,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 5. 配置根产物是否存在：
    - Cursor/Claude：`rules/`、`skills/`
    - Codex：`.codex/AGENTS.md`、`skills/`
+6. 本技能成功完成后，删除 `.Knowledge/update-check.json`（若存在），让下一次新会话重新检测并清除旧升级提示；若删除失败，在步骤 5 摘要中写明。
 
 ### 步骤 5：输出结果摘要（必须）
 
@@ -195,6 +196,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 - **SKILL 自更新**：`init` 后是否重读 `f2s-kb-upgrade/SKILL.md`；是否因文件变化 **整技能重跑**及轮次（见「init 与技能自更新」）
 - manifest / matchers 对齐结论（随 init 输出）
 - 关键文件校验结论
+- `.Knowledge/update-check.json` 清理结论（已删除 / 不存在 / 删除失败）
 - 如失败，给出下一步可执行修复建议
 
 ## 输出摘要模板（建议）
@@ -215,6 +217,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 - manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖`
 - topics.path：`全部存在` / `存在缺失（见下）`
 - agent 产物：`通过` / `异常（见下）`
+- update-check 缓存：`已删除` / `不存在` / `删除失败`
 
 ### 备注
 - <失败原因或后续建议>
@@ -239,3 +242,4 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 8. 是否输出了 manifest 与关键路径校验结果。
 9. 若失败，是否给出下一步具体命令建议。
 10. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。
+11. 成功升级后是否删除 `.Knowledge/update-check.json`，避免当天新会话继续提示旧升级信息。