@double-codeing/flow2spec 3.1.0 → 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/README.md

@@ -149,7 +149,7 @@ npx @double-codeing/flow2spec@latest init
 | `/f2s-kb-feat` | 新增小功能 |
 | `/f2s-kb-fix` | 改 BUG |
 | `/f2s-kb-sync` | 同步知识库 |
-| `/f2s-git-commit` | 提交代码 |
+| `/f2s-git-commit` | 提交代码；“快捷提交”跳过知识库覆盖检查 |
 | `/f2s-kb-add <路径>` | 接口模块入知识库 |
 
 更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)
@@ -184,4 +184,4 @@ npx @double-codeing/flow2spec@latest init
 
 ## 协议
 
-MIT. Copyright © 2026 兰涛
+MIT. Copyright © 2026 兰涛

package/cli.js

@@ -2,6 +2,7 @@
 
 const path = require("path");
 const fs = require("fs");
+const os = require("os");
 const readline = require("readline");
 const runInit = require("./lib/init");
 const { AGENTS } = require("./lib/agents");
@@ -12,7 +13,7 @@ const {
   getMissingConfigFields,
 } = require("./lib/flow2specConfig");
 
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 
 const args = process.argv.slice(2);
 const sub = args[0];
@@ -23,6 +24,107 @@ const agentList = Object.entries(AGENTS)
 
 const pkg = require("./package.json");
 
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+function parseVersion(version) {
+  return String(version || "")
+    .replace(/^v/, "")
+    .split(/[.-]/)
+    .slice(0, 3)
+    .map((part) => {
+      const n = Number.parseInt(part, 10);
+      return Number.isFinite(n) ? n : 0;
+    });
+}
+
+function compareVersions(a, b) {
+  const av = parseVersion(a);
+  const bv = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (av[i] || 0) - (bv[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function updateCheckCacheFile() {
+  const safeName = String(pkg.name || "flow2spec").replace(/[^a-z0-9_.-]+/gi, "_");
+  return path.join(os.homedir(), ".flow2spec", `${safeName}-update-check.json`);
+}
+
+function readUpdateCheckCache() {
+  const file = updateCheckCacheFile();
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!data || typeof data !== "object") return null;
+    if (Date.now() - Number(data.checkedAt || 0) > UPDATE_CHECK_TTL_MS) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCheckCache(latest) {
+  try {
+    const file = updateCheckCacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      file,
+      `${JSON.stringify({ latest, checkedAt: Date.now() }, null, 2)}\n`,
+      "utf8",
+    );
+  } catch {
+    // 更新检查不能影响主命令。
+  }
+}
+
+function queryLatestPackageVersion() {
+  const cached = readUpdateCheckCache();
+  if (cached?.latest) return cached.latest;
+  const latest = execFileSync("npm", ["view", pkg.name, "version"], {
+    encoding: "utf8",
+    timeout: 2000,
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+  if (latest) writeUpdateCheckCache(latest);
+  return latest;
+}
+
+function shouldCheckForUpdates() {
+  if (process.env.FLOW2SPEC_SKIP_UPDATE_CHECK === "1") return false;
+  if (process.env.CI) return false;
+  if (!process.stdout.isTTY) return false;
+  return Boolean(pkg.name && pkg.version);
+}
+
+function printKnowledgeUpgradeHint(latest) {
+  console.log(`
+⚠ Flow2Spec 有新版本 v${latest}（当前 v${pkg.version}）
+建议先更新包：
+  flow2spec update
+
+更新后请在 Agent 对话中执行：
+  f2s-kb-upgrade
+
+用于对齐项目知识库模板、manifest/matchers 与配置根产物；不要把单独 flow2spec init 当作知识库升级。
+`);
+}
+
+function maybePrintUpdateNotice() {
+  if (!shouldCheckForUpdates()) return;
+  try {
+    const latest = queryLatestPackageVersion();
+    if (latest && compareVersions(latest, pkg.version) > 0) {
+      printKnowledgeUpgradeHint(latest);
+    }
+  } catch {
+    // 静默跳过，不能因为网络或 npm registry 影响主命令。
+  }
+}
+
 const help = `
 Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
 
@@ -30,7 +132,7 @@ Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
   flow2spec init [agent ...] [--reset-knowledge] [--yes]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
   flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
   flow2spec version             显示当前 flow2spec 版本
-  flow2spec update              更新 flow2spec 到最新版本
+  flow2spec update              更新 flow2spec 到最新版本；更新后提示执行 f2s-kb-upgrade
   flow2spec --help              显示本说明
 
 agent（可多个，空格分隔；省略时交互选择）：
@@ -47,13 +149,14 @@ init 会:
   1. 交互询问要初始化的 AI 工具（cursor / claude / codex，可多选）；已通过参数指定则跳过。
      传 --yes 或非 TTY 环境时跳过问答，使用默认值。
   2. 对 ${CONFIG_FILENAME} 中缺失的配置字段逐项提问（已有字段不覆盖）。
-     传 --yes 时所有缺失字段使用默认值（均为 false）。
+     传 --yes 时所有缺失字段使用各自默认值。
   3. 默认仅补齐 .Knowledge 缺失模板，并对路由清单做包级/结构增量对齐（manifest-routing + matcherPath 分片；关键词仅写在 matchers/*.json）；不替代 f2s-* 对业务文档与路由内容的写入。
      传 --reset-knowledge 时才会强制用模板覆盖 .Knowledge 中模板承载部分。
   4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 在仓库根写入完整 AGENTS.md，.codex/ 写入指针）。
-     Claude 额外写入 .claude/hooks/f2s-config-inject.js 与 .claude/settings.json（PreToolUse hook），
-     在调用 f2s-* Skill 时注入配置摘要；配置缺失、JSON 无效或 hook 异常时也会注入默认语义说明，避免静默。
-     Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件。
+     Claude 额外写入 .claude/hooks/f2s-config-session.js、f2s-config-inject.js 与 .claude/settings.json：
+     SessionStart 注入一次配置摘要；PreToolUse 仅在调用 f2s-* Skill 时提示首步必须 Read 配置。
+     Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件；
+     并写入 .cursor/hooks.json，在 sessionStart 自动检测知识库版本。
      Codex：仓库根 AGENTS.md（CLI 自动发现，完整条令）；.codex/AGENTS.md 为指针。
   5. 每次 init 将包内 templates/knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。）
   6. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。
@@ -68,6 +171,7 @@ if (sub === "--help" || sub === "-h" || !sub) {
 
 if (sub === "version" || sub === "--version" || sub === "-v") {
   console.log(`flow2spec v${pkg.version}`);
+  maybePrintUpdateNotice();
   process.exit(0);
 }
 
@@ -75,19 +179,25 @@ if (sub === "update") {
   console.log(`当前版本: v${pkg.version}`);
   console.log("正在检查最新版本...");
   try {
-    const latest = execSync(`npm view ${pkg.name} version`, {
+    const latest = execFileSync("npm", ["view", pkg.name, "version"], {
       encoding: "utf8",
     }).trim();
-    if (latest === pkg.version) {
-      console.log(`已是最新版本 v${latest}`);
+    if (compareVersions(latest, pkg.version) <= 0) {
+      console.log(`当前版本不低于 npm 最新版本 v${latest}`);
       process.exit(0);
     }
     console.log(`发现新版本: v${latest}`);
     console.log("正在更新...");
-    execSync(`npm install -g ${pkg.name}@latest`, {
+    execFileSync("npm", ["install", "-g", `${pkg.name}@latest`], {
       stdio: "inherit",
     });
     console.log(`\n✓ 已更新到 v${latest}`);
+    console.log(`
+下一步：请在需要升级的项目 Agent 对话中执行：
+  f2s-kb-upgrade
+
+用于对齐项目知识库模板、manifest/matchers 与配置根产物；不要把单独 flow2spec init 当作知识库升级。
+`);
   } catch (e) {
     console.error("更新失败:", e.message || e);
     process.exit(1);
@@ -296,7 +406,7 @@ if (sub === "init") {
           return `  - ${root}/：（${label}）skills/、topics/、AGENTS.md（指针）；仓库根 AGENTS.md（完整）`;
         if (id === "claude") {
           const hookLine = claudeHooksResult?.settingsChanged
-            ? "rules/、skills/、hooks/f2s-config-inject.js、settings.json（已写入 f2s PreToolUse hook）"
+            ? "rules/、skills/、hooks/f2s-config-session.js、hooks/f2s-config-inject.js、settings.json（已写入 f2s SessionStart/PreToolUse hooks）"
             : "rules/、skills/（settings.json 中 f2s hook 已存在，跳过）";
           return `  - ${root}/：（${label}）${hookLine}`;
         }
@@ -326,6 +436,7 @@ ${lines.join("\n")}
 
 建议阅读 README 或 docs/使用说明.md，按「规则在配置根、文档在 .Knowledge」的方式使用。
 `);
+      maybePrintUpdateNotice();
     })
     .catch((e) => {
       console.error(e.message || e);

package/docs/en/architecture.md

@@ -136,9 +136,9 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```

package/docs/en/commands-reference.md

@@ -15,7 +15,7 @@
 | `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |
 | `/f2s-req-backend` | Generate backend technical proposal from clarified requirements | Requirements |
 | `/f2s-req-plan` | Break a technical proposal into a task checklist and implement (always creates tasks, regardless of `changeTracking.*` config) | Requirements |
-| `/f2s-git-commit` | Commit code with automatic knowledge base coverage check | Commit |
+| `/f2s-git-commit` | Commit code; checks knowledge base coverage by default, skips that check in "quick commit" mode | Commit |
 | `/f2s-kb-feat` | Add new capability + sync knowledge base | KB Maintenance |
 | `/f2s-kb-fix` | Fix a bug + auto-sync knowledge base | KB Maintenance |
 | `/f2s-kb-sync` | Sink implemented capabilities from the conversation into the knowledge base | KB Maintenance |
@@ -288,13 +288,14 @@
 
 ### `f2s-git-commit`
 
-**Purpose**: Executes a Git commit after code is written. Automatically checks changed files, compares knowledge base coverage, prompts the user about capabilities not yet imported, and performs the commit after the commit message is confirmed.
+**Purpose**: Executes a Git commit after code is written. By default it checks changed files and knowledge base coverage, prompting the user about capabilities not yet imported. If the user explicitly asks for a "quick commit", it skips the knowledge base coverage check. Before committing, it displays the commit message subject and then runs `git commit`.
 
-**How It Works**: Layers a "knowledge base coverage gate" on top of `git commit` — infer touched capability areas from `git diff`, cross-check against `.Knowledge/topics/` and `stock-docs/`, and decide whether changed capabilities are documented in the knowledge base. If not covered, block and offer three choices (document first / skip / cancel) to avoid silent drift where "code exists but the knowledge base does not know." Commit messages use emoji + Conventional Commits for consistent, machine-friendly `git log`.
+**How It Works**: Layers a "knowledge base coverage gate" on top of `git commit` — infer touched capability areas from `git diff`, cross-check against `.Knowledge/topics/` and `stock-docs/`, and decide whether changed capabilities are documented in the knowledge base. If not covered, block and offer three choices (document first / skip / cancel) to avoid silent drift where "code exists but the knowledge base does not know." Quick commit mode only skips this coverage gate; it does not skip conflict checks, message display, precise `git add`, or git hooks. Commit messages use emoji + Conventional Commits for consistent, machine-friendly `git log`.
 
 **Use Cases**:
 - Committing code after each feature implementation or bug fix
 - Wanting reminders about knowledge base coverage at commit time
+- Explicitly wanting to skip this commit's coverage check with a quick commit
 - Needing AI help to generate meaningful commit messages
 
 **Relationships**:
@@ -304,7 +305,7 @@
 
 **Execution Flow**:
 1. `git status --short` + `git diff HEAD` to classify files into staged / unstaged / untracked; immediately terminates if merge conflict markers are found
-2. Compare `.Knowledge/topics/` and `stock-docs/` to determine whether the changed capabilities have been imported; skips and notifies if `.Knowledge` does not exist
+2. By default, compare `.Knowledge/topics/` and `stock-docs/` to determine whether the changed capabilities have been imported; skips and notifies if `.Knowledge` does not exist; skips this step when the user asks for a quick commit
 3. If not covered, prompt the user to choose: A) Import first, then commit / B) Commit now, import later / C) Cancel
 4. Generate a commit message draft based on `git diff` content, wait for user confirmation or changes
 5. `git add <specific files>` + `git commit`; if a hook fails, prompt for fix, do not skip
@@ -314,7 +315,7 @@
 - `git add -A` / `git add .` is forbidden; only add confirmed changed files
 - `--no-verify` is forbidden; hook failures must be fixed and retried
 - Auto-push is forbidden
-- The commit message must be confirmed by the user; silent commits are not allowed
+- The commit message subject must be displayed before committing; an extra user confirmation round is not required
 
 **Sub-Agent Invocation**: None (full interactive confirmation, handled within the main agent)
 
@@ -497,6 +498,9 @@
 **Use Cases**:
 - After a `flow2spec` package version upgrade, upgrade the project knowledge base template
 - Upgrade an old project to the latest structure
+- When interactive `flow2spec version` / `flow2spec init` detects a newer npm version, the CLI prompts you to run `flow2spec update`, then execute this skill in the Agent conversation
+- When Cursor detects an older knowledge-base version through `.cursor/hooks.json` on `sessionStart`, it prompts you to execute this skill
+- When Codex detects an older knowledge-base version through `.codex/hooks.json` on `SessionStart`, it prompts you to execute this skill (new or changed hooks must be trusted through `/hooks` first)
 
 **Relationships**:
 - **Prerequisite**: `f2s-kb-migrate` (V1 flow) or an existing `.Knowledge/`
@@ -590,11 +594,11 @@ The following are not skill commands but rules activated by trigger words to gui
 
 ## 6) Sub-Agent Configuration
 
-Controlled via `flow2spec.config.json` at the project root (all fields default to `false`).
+Controlled via `flow2spec.config.json` at the project root. Defaults: `subAgent=false`, `switchAgentVerification=false`, `changeTracking.feat=true`, `changeTracking.fix=false`, `changeTracking.implement=true`.
 
 ### How Different Products "See" the Configuration (use with the field table below)
 
-`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude hooks / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.md — Agent Orchestration § 5.1](./design-principles.md); talk / deck pacing in [intro deck HTML](../../presentations/flow2spec-intro-public-en/index.html) (internal); Chinese source in `flow2spec-intro-draft`, config section). **The full path and table are maintained in one place**: [usage-guide.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.md).
+`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude SessionStart summary + PreToolUse guard / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.md — Agent Orchestration § 5.1](./design-principles.md); talk / deck pacing in [intro deck HTML](../../presentations/flow2spec-intro-public-en/index.html) (internal); Chinese source in `flow2spec-intro-draft`, config section). **The full path and table are maintained in one place**: [usage-guide.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.md).
 
 ### `subAgent` Field
 
@@ -617,9 +621,9 @@ A nested object, with each skill independently controlled:
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```
@@ -648,4 +652,4 @@ Related Documents:
 - [Usage Guide](./usage-guide.md)
 - [Directory Conventions](./directory-conventions.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/design-principles.md

@@ -477,8 +477,10 @@ Session context itself is an information source  ·  no need for users to organi
 
 | Mechanism | Design Intent |
 | --- | --- |
-| **Cursor `f2s-config-check.mdc`** | Rule-layer enforcement: "Read before skill body." |
-| **Claude `f2s-config-inject` PreToolUse** | Injects parsed results when calling **`f2s-*` Skill**; **missing file / broken JSON / hook exception** still outputs a note with default semantics, no silent failure. |
+| **Cursor `f2s-config-check.mdc`** | Rule-layer enforcement: "Read before skill body"; Cursor hooks are used for update checks only, not automatic config reads. |
+| **Claude `f2s-config-session` SessionStart** | Injects one config summary when the conversation starts, reducing the chance that the setting is forgotten. |
+| **Claude `f2s-config-inject` PreToolUse** | Only guards **`f2s-*` Skill** calls by reminding the agent that the first skill-body action must be Read; it no longer repeatedly injects the full config. |
+| **Codex `AGENTS.md` / `.codex/topics/f2s-config-check.md`** | Text-layer enforcement: "Read before skill body"; Codex hooks are used for update checks only, not automatic config reads. |
 | **Codex `AGENTS.md` + `renderProjectConfigBlock`** | Top-level **Read** hard constraint + **init snapshot table** (if inconsistent with disk, Read takes precedence). |
 | **Knowledge base `config-precheck` topic** | When routing hits, provides only **summary** and a pointer to the Codex full text, **not** a substitute for Read JSON. |
 
@@ -562,8 +564,9 @@ flow2spec.config.json
   switchAgentVerification: false → writer-side self-verify, daily use
   switchAgentVerification: true  → cross-verification, high-confidence critical scenarios
 
-  changeTracking.feat/fix/implement: false → no task checklist created
-  changeTracking.feat/fix/implement: true  → automatic task checklist creation when corresponding skills run, supporting cross-session continuation
+  changeTracking.feat: true        → f2s-kb-feat creates a task checklist by default
+  changeTracking.fix: false        → f2s-kb-fix does not create a task checklist by default
+  changeTracking.implement: true   → implement-tech-design creates a task checklist by default
 
   Three orthogonal dimensions · each skill can further refine and override global config
 ```
@@ -615,4 +618,4 @@ Best suited when: has scale · long-term iteration · multi-tool or multi-person
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

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

@@ -27,9 +27,9 @@ Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual val
 
 | Client | `init` Output & Behavior | Description |
 | --- | --- | --- |
-| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Rule requires: **Read(`flow2spec.config.json`)** before entering skill body. |
-| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` (PreToolUse, `Skill` matching) | Injects a config summary when invoking **`f2s-*` Skill**; when **file is missing, JSON is invalid, or hook throws an unexpected exception**, it also injects a **notice + default semantics consistent with "file not found"** to avoid silent failure; it is still recommended to **Read** for confirmation when in doubt or after config changes. |
-| **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
+| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Config reading remains rule-based: **Read(`flow2spec.config.json`)** before entering skill body. Cursor hooks are used for update checks only, not automatic config reads. |
+| **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` injects one config summary; `PreToolUse` only guards **`f2s-*` Skill** calls by reminding the agent that the first skill-body action must be **Read**. Neither replaces the disk read. |
+| **Codex** | root `AGENTS.md` mandatory step + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | Config reading remains rule-based: **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** and disk Read takes precedence. Codex hooks are used for update checks only, not automatic config reads. |
 | **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
 
 For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.md).
@@ -110,6 +110,14 @@ f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade
 f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0)
 ```
 
+In interactive terminals, the Flow2Spec CLI checks the latest npm version with a cache when running `flow2spec version` / `flow2spec init`. If a newer version exists, it prompts you to run `flow2spec update`, then execute `f2s-kb-upgrade` in the Agent conversation to align the project knowledge templates, manifest/matchers, and agent config roots. Failed update checks are skipped silently and do not affect the current command; checks are disabled in `CI`, non-TTY sessions, or when `FLOW2SPEC_SKIP_UPDATE_CHECK=1` is set.
+
+After `flow2spec init codex`, Codex projects include `.codex/hooks.json` and `.codex/hooks/f2s-update-check.js`. The hook runs on Codex `SessionStart` for `startup|resume` and checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through `/hooks` in Codex. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip the check.
+
+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
@@ -154,4 +162,4 @@ Skills are triggered by matching `name` and `description`. Files are located und
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/usage-scenarios.md

@@ -4,7 +4,7 @@
 
 The following examples revolve around the same e-commerce project, covering the full pipeline from requirements clarification through post-launch maintenance.
 
-**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
+**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`; `changeTracking.feat/implement: true`, `changeTracking.fix: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
 
 ---
 
@@ -193,4 +193,4 @@ The following examples revolve around the same e-commerce project, covering the
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
-- [Architecture](./architecture.md)
+- [Architecture](./architecture.md)

package/docs//344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -138,9 +138,9 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```

package/docs//344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md

@@ -4,7 +4,7 @@
 
 以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。
 
-**前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
+**前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`；`changeTracking.feat/implement: true`，`changeTracking.fix: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
 
 ---
 

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

@@ -30,9 +30,9 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 
 | 端               | `init` 落盘与行为                                                                          | 说明                                                                                                                                                                                     |
 | --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。                                                                                                                                         |
-| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。                                                                |
-| **Codex**       | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表                        | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
+| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 配置读取走文本约束：技能正文前先 **Read(`flow2spec.config.json`)**；Cursor hook 仅用于版本更新检测，不自动读取配置。                                                                                                  |
+| **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` 仅注入一次配置摘要；`PreToolUse` 仅在调用 **`f2s-*` Skill** 时做守门提示，提醒首步必须 **Read**。两者都不替代磁盘 Read。                                                                |
+| **Codex**       | 根 `AGENTS.md` 顶部强制步骤 + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | 配置读取走文本约束：**Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。Codex hook 仅用于版本更新检测，不自动读取配置。 |
 | **知识库（可选）**     | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时                              | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。                                                                      |
 
 
@@ -114,6 +114,14 @@ f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade
 f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0）
 ```
 
+Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会按缓存检查 npm 最新版本；若发现新版本，会提示先执行 `flow2spec update`，随后在 Agent 对话中执行 `f2s-kb-upgrade`，用于对齐项目知识库模板、manifest/matchers 与配置根产物。更新检查失败会静默跳过，不影响当前命令；`CI`、非 TTY 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时不检查。
+
+Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json` 与 `.codex/hooks/f2s-update-check.js`，在 Codex `SessionStart` 的 `startup|resume` 事件自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。
+
+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 执行配置
@@ -159,4 +167,3 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 - [目录与路径约定](./目录与路径约定.md)
 - [体系与原理](./体系与原理.md)
 - [使用案例-模拟对话](./使用案例-模拟对话.md)
-

package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -15,7 +15,7 @@
 | `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |
 | `/f2s-req-backend` | 基于澄清结果生成后端技术方案文档 | 需求与方案 |
 | `/f2s-req-plan` | 按技术方案拆任务清单，支持并行实现 （不依赖 `changeTracking.*` 配置） | 需求与方案 |
-| `/f2s-git-commit` | 提交代码，自动检查知识库覆盖情况 | 提交 |
+| `/f2s-git-commit` | 提交代码，默认检查知识库覆盖；说“快捷提交”时跳过覆盖检查 | 提交 |
 | `/f2s-kb-feat` | 新增能力，补全实现 + 同步知识库 | 知识库维护 |
 | `/f2s-kb-fix` | 修复 BUG + 自动同步知识库 | 知识库维护 |
 | `/f2s-kb-sync` | 将会话中已实现能力沉淀回知识库 | 知识库维护 |
@@ -337,14 +337,15 @@
 
 ### `f2s-git-commit`
 
-**作用**：代码写完后执行 Git 提交。自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理，确认提交信息后执行 commit。
+**作用**：代码写完后执行 Git 提交。默认自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理；用户明确说“快捷提交”时跳过知识库覆盖检查。提交前会展示提交信息首行，然后直接执行 commit。
 
-**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
+**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。快捷提交模式只跳过这层覆盖门控，不跳过冲突检查、提交信息展示、精确 `git add`、git hooks。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
 
 **使用场景**：
 
 - 每次功能实现或 Bug 修复后提交代码
 - 希望在提交时得到知识库覆盖情况的提醒
+- 已明确不需要本次覆盖检查，只想快捷提交
 - 需要 AI 帮助生成有意义的提交信息
 
 **关联关系**：
@@ -356,7 +357,7 @@
 **执行流程**：
 
 1. `git status --short` + `git diff HEAD` 区分 staged / unstaged / untracked 三类文件；发现 merge conflict 标记立即终止
-2. 对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示
+2. 默认对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示；用户说“快捷提交”时跳过本步
 3. 未覆盖时提示用户选择：A) 先补录再提交 / B) 先提交稍后补录 / C) 取消
 4. 基于 `git diff` 实际内容生成提交信息草稿，等待用户确认或修改
 5. `git add <具体文件>` + `git commit`；hook 失败则提示修复，不跳过
@@ -367,7 +368,7 @@
 - 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件
 - 禁止 `--no-verify`，hook 失败须修复后重试
 - 禁止自动 push
-- 提交信息必须经用户确认，不可静默提交
+- 提交前必须展示提交信息首行；不要求用户额外确认 commit
 
 **子 agent 调用**：无（全程交互确认，主 agent 内完成）
 
@@ -585,6 +586,9 @@
 
 - flow2spec 包版本升级后，升级项目知识库模板
 - 旧项目升级到最新结构
+- CLI 在交互式 `flow2spec version` / `flow2spec init` 中发现 npm 有新版本后，会提示先 `flow2spec update`，再在 Agent 对话中执行本技能
+- Cursor 通过 `.cursor/hooks.json` 在 `sessionStart` 自动检测到知识库版本落后后，会提示执行本技能
+- Codex 通过 `.codex/hooks.json` 在 `SessionStart` 自动检测到知识库版本落后后，会提示执行本技能（首次或变更后需在 Codex `/hooks` 中信任）
 
 **关联关系**：
 
@@ -689,11 +693,11 @@
 
 ## 6) 子 Agent 配置说明
 
-通过项目根 `flow2spec.config.json` 控制（字段默认均为 `false`）。
+通过项目根 `flow2spec.config.json` 控制。默认值：`subAgent=false`、`switchAgentVerification=false`、`changeTracking.feat=true`、`changeTracking.fix=false`、`changeTracking.implement=true`。
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
+`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude SessionStart 摘要 + PreToolUse 守门 / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
 
 ### `subAgent` 字段
 
@@ -720,9 +724,9 @@
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```
@@ -755,4 +759,3 @@
 - [目录与路径约定](./目录与路径约定.md)
 - [体系与原理](./体系与原理.md)
 - [使用案例-模拟对话](./使用案例-模拟对话.md)
-

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。
+
 ---
 
 ## 相关文档