@double-codeing/flow2spec 2.2.3 → 3.0.7

package/templates/knowledge/topics/f2s-stock-docs-vs-req-docs.md

@@ -0,0 +1,25 @@
+# stock-docs-vs-req-docs（路由摘要）
+
+> **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。  
+> **Codex**：不读 `rules/`，须执行 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**（由 `flow2spec init` 从模板 `rules` 自动镜像）中的等效约束。
+
+## 本文件作用
+
+- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`stock-docs-vs-req-docs`**。
+- 仅保留**目录分工**记忆点。
+
+## 目录分工（须与规则一致）
+
+| 目录 | 用途 |
+| --- | --- |
+| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-ctx-build` / `f2s-doc-final` 等优先落盘。 |
+| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 |
+
+**原则**：按方案写代码只读 **`req-docs`**；不要把 **`stock-docs`** 当编码直接输入。
+
+## 下一步读什么
+
+| 环境 | 下一步 |
+| --- | --- |
+| Cursor / Claude | 打开或 @ **`rules/f2s-stock-docs-vs-req-docs`**。 |
+| Codex | 读 **`.codex/topics/f2s-stock-docs-vs-req-docs.md`**。 |

package/templates/rules/f2s-config-check.mdc

@@ -0,0 +1,35 @@
+---
+description: 执行任何 f2s-* 技能前强制读取 flow2spec.config.json，确定 subAgent 与 switchAgentVerification 实际值
+alwaysApply: true
+---
+
+# f2s 技能前置强制步骤
+
+**执行任何 `f2s-*` 技能的第一个动作，必须用 Read 工具读取项目根 `flow2spec.config.json`**，获取 `subAgent` 与 `switchAgentVerification` 的实际值，再决定后续编排方式。
+
+```
+必须执行：Read("flow2spec.config.json")  ← 技能正文任何步骤之前
+```
+
+| 读取结果 | 行为 |
+|---------|------|
+| `subAgent: true` | 按技能 SKILL.md 的 B/C 模式派子 agent 并行扫描，主 agent 合并落盘 |
+| `subAgent: false` | 全部在主 agent 内完成，不得拆子 agent |
+| `switchAgentVerification: true` | 子 agent 落盘的由主 agent 校验；主 agent 落盘的由子 agent 校验（须 subAgent=true 且已拆子任务） |
+| `switchAgentVerification: false` | 落盘侧自验，不交叉 |
+| 文件不存在 | 所有字段均视为 `false` |
+
+**Claude Code**：若已启用 `f2s-config-inject` PreToolUse hook，调用 `f2s-*` Skill 时会注入配置摘要；**文件缺失、JSON 损坏或 hook 异常时也会注入说明与默认语义**，不静默。仍建议在存疑或刚改过配置时用 `Read` 与磁盘核对。
+
+### changeTracking（变更追踪）
+
+| 字段 | 生效技能 | 行为 |
+|------|---------|------|
+| `changeTracking.feat: true` | `f2s-kb-feat` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 |
+| `changeTracking.feat: false` | `f2s-kb-feat` | 步骤 0 跳过，不创建 `.task/` 目录 |
+| `changeTracking.fix: true` | `f2s-kb-fix` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 |
+| `changeTracking.fix: false` | `f2s-kb-fix` | 步骤 0 跳过，不创建 `.task/` 目录 |
+| `changeTracking.implement: true` | `f2s-implement-tech-design` | **步骤 2.5 写入任务清单、步骤 2.6 随实现同步打钩 `task.md`、步骤 5 满足归档门禁后归档** |
+| `changeTracking.implement: false` | `f2s-implement-tech-design` | 步骤 2.5、2.6 和步骤 5 的变更追踪部分跳过 |
+
+**禁止在未读该文件的情况下进入技能正文的任何执行步骤。**

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

@@ -0,0 +1,88 @@
+---
+description: Flow2Spec 统一知识库入口，按 .Knowledge 渐进式读取
+alwaysApply: true
+---
+
+# Flow2Spec 统一入口规则
+
+本项目知识库已统一到 `.Knowledge/`，请按以下顺序读取，避免无范围检索。
+
+## 项目根 CLI 开关（必须按需读取）
+
+业务仓库**项目根** `flow2spec.config.json`（`flow2spec init` 在文件缺失时从包模板补齐）含布尔字段 **`subAgent`**、**`switchAgentVerification`**（**切换 agent 校验**），默认 `false`。执行任意 **`f2s-*` 技能**或与 Flow2Spec 初始化相关的说明前，须读取该文件；技能或规则中凡写「仅当 `subAgent` / `switchAgentVerification` 为 true」的步骤，**必须按文件实际值决定是否执行**；缺失字段或文件不存在时均视为 `false`。
+
+> **`init` 与择路**：包模板 **`templates/rules/f2s-flow2spec-unified-entry.mdc`** 经 **`flow2spec init`** 写入业务仓库配置根 **`rules/f2s-flow2spec-unified-entry.*`**，并（去 frontmatter）镜像 **`.codex/topics/f2s-flow2spec-unified-entry.md`**；两处正文同源，按需读一处即可。技能引「统一入口」时，在 **Codex** 以 **`.codex/topics/f2s-flow2spec-unified-entry.md`** 为准。
+
+### 两字段语义（模板约定）
+
+- **`subAgent`**：`f2s-*` 技能若规定某步骤「用子 agent 执行」，则 **`true`** 时按技能使用子 agent，**`false`** 时在主 agent 内完成。用户可在对话中要求「**仅当**本项为 **`true`** 时，由主 agent **动态判断**哪些子任务适合交给子 agent」——**仅当配置为 `true` 时该要求有效**；配置为 `false` 时凡依赖拆子 agent 的该段说明**不生效**，全部在主 agent 完成。**各 `f2s-*` 在工作哪一阶段必须或建议使用子 agent** 由包内技能正文逐步约定，**当前尚未在模板层给出统一阶段表**；以技能为准并受本项约束。
+- **`switchAgentVerification`（切换 agent 校验）**：落盘或变更后的**验证/复核**（对照清单、diff、自检）**不是**「一律在主 agent」；默认以**落盘侧所在 agent 为「当前 agent」**，在该会话内完成校验（**子 agent 落盘的就在子 agent 内验，主 agent 落盘的就在主 agent 内验**）。**仅当**① 配置 **`switchAgentVerification` 为 `true`**，**且** ② **当前 `f2s-*` 技能正文**对该步骤**明确写出**「当 **`switchAgentVerification`** 为 **`true`**」时，才启用**交叉校验**：**子 agent 落盘的 → 由主 agent 校验**；**主 agent 落盘的 → 由子 agent 校验**（**须**已存在子 agent 会话，即 **`subAgent` 为 `true`** 且实际拆出子任务；若 **`subAgent` 为 `false`**，无子侧可承接，**「主落盘→子验」不发生**，校验**全部在主 agent 内**完成）。配置为 `false`、或技能未写依赖本项、或用户仅泛泛要求「给对方验」的：**不**启用交叉，仍在**落盘侧 agent**内完成验证。
+
+### Git worktree 与子任务工作目录卫生（`subAgent: true` 或并行子任务时必读）
+
+部分环境会为子 agent / 并行尝试创建 **独立 `git worktree`** 或等价隔离目录。规则如下：
+
+1. **谁创建谁收尾**：子侧创建则子侧在返回前尽量清理；若子会话已结束无法清理，**主 agent 合并结果后**必须执行清理，**禁止**依赖「稍后自动回收」。
+2. **收尾动作（必须）**：对**仅为本次子任务**添加的 worktree，在合并或丢弃该子任务结果后执行 `git worktree remove <path>`（工作区干净仍失败时再用 `git worktree remove --force <path>`，**须确认**该路径无他人未提交修改）；随后 `git worktree list` 自检，**禁止**留下已知孤儿路径。
+3. **中断 / 用户换题前**：若本会话曾添加 worktree，在结束前**必须**完成上述移除或在 `task.md`「## 备注」写明残留路径与删除命令，并视情况写入 **`user-todos.md`** 请用户本地执行（见 `f2s-task`）。
+4. **禁止**：子任务已结束、主分支已继续开发，仍长期保留仅用于尝试的 worktree 目录（易造成混淆提交、磁盘堆积）。
+
+## 读取顺序（必须）
+
+1. 先读 `.Knowledge/manifest-routing.json`，优先按 `taskToTopicRules` 路由；按需根据 `matcherPath` 读取 matcher 分片获取 `includeAny` 关键词；无法命中时进入补召回阶段。
+   - 若命中主题在 `topicDependencies` 中存在依赖，先读依赖主题，再读主主题。
+   - 路由清单仅通过 `f2s-*` 技能流程维护，不依赖额外 CLI 子命令。
+2. `.Knowledge/index.md` 按需读取，仅用于确认主题语义与边界。
+3. 再读 `.Knowledge/topics/<topic>.md`（**路由摘要**：主题 id、路径约定、下一步指针）；若主题为 **`implement-tech-design`** 或 **`stock-docs-vs-req-docs`**，**必须继续读取**配置根 **`rules/f2s-implement-tech-design.*` / `rules/f2s-stock-docs-vs-req-docs.*` 全文**作为执行依据（`.Knowledge/topics` 内同名文件不重复长文）。
+4. 若需要背景，再读 `.Knowledge/stock-docs/<doc>.md`。
+5. 仅在前四步不足时下钻业务源码。
+6. 命中后必须执行 `match -> expand -> verify -> act`：
+   - `match`：先取主候选；
+   - `expand`：展开 `topicDependencies`，并保留次高候选做补充校验；
+   - `verify`：执行前做缺口检查（关键主题/边界/上下文是否缺失）；
+   - `act`：仅在置信度足够时执行；低置信度必须先澄清。
+7. 仅在以下条件之一成立时，允许执行跨 matcher 全量补检索（top-k）：
+   - `taskToTopicRules` 无命中；
+   - 主候选与次候选分差过小（低置信度）；
+   - 缺口检查失败（关键主题/依赖/上下文缺失）；
+   - 用户明确要求“全量检查/不要遗漏”。
+
+## 任务分流
+
+- 技术方案实现：先读 `.Knowledge/topics/f2s-implement-tech-design.md`（摘要），再读 **`rules/f2s-implement-tech-design.*` 全文**；需求文档默认位于 `.Knowledge/req-docs/`。
+- 目录边界判断：先读 `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md`（摘要），再读 **`rules/f2s-stock-docs-vs-req-docs.*` 全文**。
+
+## 机读事实源口径（规则层）
+
+- `taskToTopicRules`：任务路由第一优先级。
+- `taskToTopicRules[].matcherPath`：匹配词分片直链路径，按需读取单个 matcher 文件。
+- `taskToTopicRules[].matcherId`：matcher 的稳定标识，需与 matcher 分片内 `id` 一致。
+- `topicDependencies`：主主题命中后先加载依赖主题。
+- `matcherPath(includeAny)`：任务关键词匹配词表。
+- `fallbackTopic`：任务与关键词都未命中时必须读取，但仅作低置信度兜底，不是最终执行依据。
+- `.Knowledge/manifest-routing.json + matcherPath 分片文件` 是机读事实源（关键词仅在 `matchers/*.json`）。
+- `.Knowledge/index.md` 不是机读事实源，仅作人读导航与语义边界校验。
+- 进入 `fallbackTopic` 后，必须先补召回或澄清，再决定是否执行改动。
+
+## 知识缺口与对策（分场景）
+
+| 情况 | 对策 |
+| --- | --- |
+| **1a 库里有文档但未配路由** | 用 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补 `taskToTopicRules`、`matcherPath` 分片、`topicPaths`；扩充 `includeAny` 覆盖用户常用说法。Agent 侧：走 `fallbackTopic` 分诊并提示「需补路由」，**不**靠全仓扫文件代替配置。 |
+| **1b 命中了但上下文不够** | 先 `expand`（`topicDependencies` + 次高候选），再 `verify` 点名缺哪份 `stock-docs`/`req-docs` 或哪段 topic；仍不足则 **向用户要文档或路径**，不要无门槛跨 matcher 全量补检索。**Agent 若需下钻源码**：须先对用户做**可见的缺口说明**（已读 KB、缺什么、拟读哪 1～2 个文件），见 **`f2s-knowledge-preflight`**「缺口闸门」；**禁止**无说明地连续 `Grep`/乱序探源。 |
+| **2 库里没有对应文档** | 一次读完 routing + 已命中 matcher + 相关 topic 后，在回复中 **明确承认知识库无覆盖**，再选：下钻业务代码 / 请用户补充 `req-docs` 或 PRD。**禁止**用反复读清单假装「再找一遍就会有」。**下钻源码前**同样须满足 **`f2s-knowledge-preflight`**「缺口闸门」的可见说明。 |
+| **2a 反复读清单耗 token** | **同一任务线内** `manifest-routing.json` 视为稳定快照：再次全文读取须说明理由（例如用户声明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或**手动编辑**了 manifest/matcher）。**勿将**仅执行 **`flow2spec init`** 等同于「业务知识库已更新」：`init` 以模板补齐、配置根落盘与包级路由结构对齐为主；**stock-docs / req-docs、topics 路由摘要、matchers 词条**由 **`f2s-*` 技能流程**维护；**包模板 `templates/rules/*.mdc`** 为 Flow2Spec 规则事实源，`init` 同步到配置根 **`rules/*.mdc`**（或等价扩展名）并镜像 **`.codex/topics/*.md`**（条数与包模板一致，含统一入口与专题长文）。只读 **当前规则对应的单个** `matcherPath`；不要为枚举而遍历整个 `matchers/` 目录。`index.md` 仅在需核对主题语义时打开，禁止与 manifest 交替「刷清单」。 |
+
+### 知识缺口的执行层要点（避免「表里有写、行为没做」）
+
+- **「向用户说明」「明确承认无覆盖」必须是用户可见的自然语言**，不得仅在内部分析或工具链中隐含带过；细则与停步条件见 **`f2s-knowledge-preflight`**（缺口闸门、探索次数上限）。
+- **禁止**在命中 **1b / 2** 后，未做上述可见说明便进入「多文件 + 依赖目录」的链式探源；每出现一个新的「入口符号」就再 `Grep` 一轮，属于典型反模式。
+- **HTTP 状态、错误正文、重定向与否**等事实，**不得以训练数据或他库经验代答**；须以当前仓库内**本次已读到的实现**为准。
+
+## 禁止项
+
+- 使用 `git worktree` 或隔离目录跑子任务后，**禁止**在未 `git worktree remove` / 未交接删除命令的情况下结束会话（见上文「Git worktree 与子任务工作目录卫生」）。
+- 未查看 `.Knowledge/manifest-routing.json` 前，禁止进行全仓无范围扫描；`.Knowledge/index.md` 在需确认主题语义时再读，禁止与 manifest 交替重复读取以代替决策。
+- 禁止把 `stock-docs` 作为直接编码输入文档；按方案实现应使用 `req-docs`。
+- 禁止把 `fallbackTopic` 当作最终命中直接实施改动。
+- 禁止在不满足触发门槛时执行跨 matcher 全量补检索。

package/templates/rules/f2s-implement-tech-design.mdc

@@ -0,0 +1,144 @@
+---
+description: 当用户要求根据技术方案文档实现可运行交付物时，按本规则执行（读文档、列任务、确认、实现、待完成列表与提醒）。用户会在对话中提供技术方案文档路径（MD 或 PDF）；若为 PDF，先按 f2s-doc-pdf 转为 MD 再继续。
+globs:
+  - "**/.Knowledge/req-docs/**/*.md"
+alwaysApply: false
+---
+
+> **唯一长文**：本文件为 **implement-tech-design** 的完整执行条令。`.Knowledge/topics/f2s-implement-tech-design.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-implement-tech-design.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。
+
+> 执行口径：统一知识库路径为 `/.Knowledge/`。下文所有路径均按 `.Knowledge` 约定解释。
+
+# 基于技术方案实现交付物（通用）
+
+当用户要求根据**技术方案文档**实现可运行交付物时（用户会提供文档路径，如 `.Knowledge/req-docs/xxx.md` 或 PDF），按以下约定执行。
+
+**目录约定**：`.Knowledge/req-docs/` 放“用于实现”的技术方案；`.Knowledge/stock-docs/` 放沉淀文档，不作为直接编码输入。
+
+**触发说明**：本规则在打开 `req-docs` 下 `.md` 时自动加载（`**/req-docs/**/*.md`）。若对话前未打开技术方案，可在对话中 @ 本规则后再提供路径。
+
+- 若用户提供的是 PDF：先执行 `f2s-doc-pdf`，将 PDF 转为 `.Knowledge/req-docs/` 下 MD，再继续。
+- 若用户提供的是 MD/文本：直接读取并进入实现流程。
+
+---
+
+## 一、目标与原则
+
+- **目标**：基于技术方案实现可运行交付物，并与项目现有约定保持一致。交付物可以是前端页面/组件、后端接口/服务、数据处理逻辑、任务编排、脚本与配置等（按方案实际范围裁剪）。
+- **原则**：
+  1. **先列任务再动手**：先输出「实现任务列表」，再提问与实现。
+  2. **先读后做**：先完整理解方案、边界、依赖、验收标准，再编码。
+  3. **对齐项目约定**：目录、命名、依赖、封装方式、错误处理与项目既有风格一致。
+  4. **缺项即问**：文档未明确的关键决策先向用户确认；未回复项进入待完成列表。
+  5. **实现后可执行**：必须给出验证方式与外部待办，确保用户可落地验收。
+
+---
+
+## 二、方案要素与实现映射（通用）
+
+| 技术方案内容 | 实现动作（按项目约定落地） |
+| --- | --- |
+| 需求目标 / 范围 / 非目标 | 明确本次实现边界，避免超范围开发。 |
+| 关键流程 / 状态流转 / 时序 | 实现主流程与分支，关键判断处加简短注释。 |
+| 数据结构 / 协议 / 字段约束 | 落地类型定义、模型、校验器或契约层。 |
+| 接口 / 事件 / 消息 | 实现调用入口、事件处理、订阅或回调（按方案涉及项选择）。 |
+| 页面 / 组件 / 交互 | 实现 UI 结构、状态管理、交互流程与容错提示（若方案涉及）。 |
+| 配置 / 开关 / 环境差异 | 在项目约定位置注册并读取，补齐默认值和降级策略。 |
+| 错误码 / 异常策略 / 重试 | 统一错误返回与日志策略，保持与现有封装一致。 |
+| 发布 / 路由 / 权限 / 任务调度 | 实现对应代码并提醒用户完成平台侧配置（若方案涉及）。 |
+
+### 流程图处理（重要）
+
+- 若流程图是 PDF/图片且无文字步骤，先向用户索要文字版流程或补充文档；
+- 若已有文字步骤，严格按顺序和分支实现；
+- 无法确认分支时先提问，或按默认策略实现并写入待完成列表。
+
+---
+
+## 三、执行步骤
+
+### 步骤 1：输入标准化
+
+- PDF 输入：先执行 `f2s-doc-pdf`，得到 `.Knowledge/req-docs/*.md`。
+- MD/文本输入：直接读取。
+
+### 步骤 2：理解方案与上下文
+
+1. 读取技术方案全文，提取：目标、范围、流程、接口/交互、数据、配置、依赖、验收条件。
+2. 读取项目约定（如 README、`.Knowledge/stock-docs/`、架构说明、既有模块）以对齐实现风格。
+3. 若流程图缺文字说明，先记录缺口，进入步骤 3 一并向用户确认。
+
+### 步骤 2.5：先输出实现任务列表（必做）
+
+在提问或编码前，必须先输出任务列表（可按方案裁剪）：
+
+```markdown
+## 实现任务列表（基于《xxx》技术方案）
+
+| 序号 | 任务项 | 说明 |
+| --- | --- | --- |
+| 1 | 核心结构与数据契约 | 落地类型/模型/校验规则，明确输入输出。 |
+| 2 | 业务流程实现 | 按流程图/文字步骤实现主链路与分支。 |
+| 3 | 对外能力接入 | 接口/事件/页面交互等对外入口实现。 |
+| 4 | 配置与异常处理 | 配置注册、错误处理、重试/降级策略。 |
+| 5 | 验证与收尾 | 自测说明、待完成列表、平台侧提醒。 |
+```
+
+若 `changeTracking.implement: true`，在输出任务列表后，按 `f2s-task` 规则将本清单写入 `.task/active/<task-name>/task.md`。
+
+### 步骤 2.6：变更追踪与 `task.md` / `user-todos.md` 同步（仅当 `changeTracking.implement: true`）
+
+- 每完成实现任务列表中一项对应工作，**同一会话内**用 `Edit` 更新 `.task/active/<task-name>/task.md` 中对应 `[ ]`→`[x]`，禁止积压到收尾、禁止口头完成代替写盘（见 `f2s-task`「执行中」「中断与会话结束」）。
+- 执行过程中每出现**须用户执行**的项（改库、配环境等），**同会话内**追加到 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`「user-todos.md」）。
+
+### 步骤 3：实现前提问（必做，不可跳过）
+
+进入编码前，必须一次性列出未明确项并请用户确认。常见问题：
+
+- **范围与验收**：本次必须交付什么，哪些明确不做；
+- **技术边界**：实现在哪个模块/端（前端、后端、脚本、数据任务等）；
+- **依赖与契约**：外部接口、消息协议、数据源、鉴权方式；
+- **配置与环境**：配置 key、环境差异、默认值与灰度策略；
+- **流程图缺口**：分支条件、失败回退、超时与重试策略；
+- **发布约束**：路由、权限、调度、部署步骤是否已具备。
+
+若用户未回复某项：按合理默认或占位实现，并在待完成列表中标注“需用户确认”。
+
+### 步骤 4：按任务列表实现
+
+按方案与项目实际裁剪顺序，建议：
+
+1. 先落地数据/契约与公共抽象；
+2. 再实现主流程与核心能力；
+3. 再接入入口层（接口/页面/事件/任务）；
+4. 最后补齐配置、异常处理、日志与测试辅助。
+
+要求：复用现有依赖与封装；与项目命名/目录/风格一致；关键分支要可读、可维护。
+
+### 步骤 5：收尾输出（必做）
+
+1. **待完成列表（必须）**：列出所有待用户或平台补齐项；
+2. **实现后提醒清单（必须）**：按实际涉及内容提醒配置、依赖、数据、发布、权限、调度等；
+3. **验证建议（建议）**：给出最小可执行验证步骤（本地、测试环境或回归路径）。
+4. **用户代办落盘（仅当 `changeTracking.implement: true`）**：将步骤 5 第 1–2 点中**须用户亲自执行**的条目（改库脚本、配置、审批等）**同步追加**到 `.task/active/<task-name>/user-todos.md`（若尚无该文件则先创建，见 `f2s-task`）；禁止仅出现在对话或方案尾部的列表而不写入该文件。
+5. 若 `changeTracking.implement: true`：**先确认** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项），满足 `f2s-task` 归档门禁后，再将 `.task/active/<task-name>/` 移至 `.task/completed/<YYYYMMDD>-<task-name>/`，并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时归档。
+
+---
+
+## 四、可选补充
+
+- 若方案命名不明确，可先给出命名建议并请用户确认；
+- 若方案跨度大，可按“最小可用版本 -> 增量迭代”拆分阶段交付；
+- 若用户希望沉淀知识库，可提醒后续用 `f2s-ctx-build` 同步主题与路由。
+
+---
+
+## 五、约束与小结
+
+- PDF 必须先转 MD，再进入实现流程；
+- 不得跳过步骤 2.5（任务列表）与步骤 3（实现前提问）直接编码；
+- 若 `changeTracking.implement: true`：不得跳过步骤 2.6（随实现进度写回 `task.md` checkbox，并追加 `user-todos.md`）；归档须满足 `f2s-task` 归档门禁；
+- 输出中必须包含待完成列表与实现后提醒清单；若 `changeTracking.implement: true`，其中用户侧项须同步写入 `user-todos.md`；
+- 内容保持通用，不预设“仅后端”场景，按方案实际范围裁剪实现对象。
+
+完成时可用一句话总结：已基于《xxx》技术方案完成本轮实现并给出待完成与验证建议，请按清单补齐平台与环境侧配置后验收。

package/templates/rules/f2s-karpathy-guidelines.mdc

@@ -0,0 +1,77 @@
+---
+description: Karpathy 式编码行为准则：先澄清假设、极简实现、只改必要处、用可验证目标驱动执行。与 f2s-* 规则并存；流程类硬约束以 f2s 为准。
+alwaysApply: true
+---
+
+# Karpathy 式编码行为准则
+
+> 来源与同步：[forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)（MIT），思想来自 [Andrej Karpathy 对 LLM 写代码常见问题的观察](https://x.com/karpathy/status/2015883857489522876)。与项目内 Flow2Spec / `f2s-*` 规则**并行**；若某条与 f2s 强制步骤冲突，**以 f2s 与项目约定为准**。
+
+用于减少常见「模型写代码」失误的行为约定。
+
+**取舍：** 这些准则偏向**稳妥而非一味求快**；对明显琐碎的修改（如单行笔误）可自行把握，不必条条刻板执行。
+
+## 1. 先想清楚再写代码
+
+**不要默认、不要藏困惑、把权衡摆到台面上。**
+
+动手实现前：
+
+- **假设要说清楚**；不确定就问，不要猜。
+- **有多种理解时并列说明**，不要悄悄选一种就跑。
+- **若有更简单做法**，主动提出；该反对时要反对。
+- **说不清就停**：点名哪里困惑，再向用户要信息。
+
+## 2. 简单优先
+
+**用最少代码解决问题，不做臆测性扩展。**
+
+- 不要超出需求加功能。
+- 不要为只用一次的代码抽抽象。
+- 不要加未被要求的「灵活性」「可配置」。
+- 不要为几乎不可能的场景堆错误处理。
+- 若写了 200 行其实 50 行就够，**重写**。
+
+自问：「资深工程师会不会觉得过度设计？」若是，就简化。
+
+## 3. 手术式修改
+
+**只动该动的；只收拾自己弄乱的。**
+
+改已有代码时：
+
+- 不要顺手「优化」相邻代码、注释或格式。
+- 不要重构没坏的东西。
+- **风格对齐现有代码**，即使你个人偏好不同。
+- 若发现与任务无关的死代码，**可以提一嘴，不要擅自删**。
+
+若你的改动产生了孤儿引用/变量：
+
+- **删掉因你这次改动而不再使用的** import、变量、函数。
+- **不要**在用户未要求时删除**原本就存在**的死代码。
+
+检验标准：**每一行改动都能追溯到用户的明确诉求。**
+
+## 4. 目标驱动执行
+
+**先定义成功标准，再循环直到可验证地达成。**
+
+把任务变成可验证目标，例如：
+
+- 「加校验」→「先写非法入参测试，再改到通过」
+- 「修 bug」→「先写能复现的测试，再改到通过」
+- 「重构 X」→「前后测试套件均通过」
+
+多步骤任务可写简短计划：
+
+```
+1. [步骤] → 验证：[检查方式]
+2. [步骤] → 验证：[检查方式]
+3. [步骤] → 验证：[检查方式]
+```
+
+成功标准越具体，越能独立迭代；含糊的「跑通就行」会逼出反复追问。
+
+---
+
+**准则在起作用的信号：** diff 里无关改动变少、因过度设计返工变少、**澄清问题出现在实现之前**而不是做错之后。

package/templates/rules/f2s-knowledge-preflight.mdc

@@ -0,0 +1,70 @@
+---
+description: 普通提问也须先读 .Knowledge 机读路由，再搜代码；硬约束首工具调用
+alwaysApply: true
+---
+
+# Flow2Spec 知识库首读（KB Preflight）
+
+本条与 `f2s-flow2spec-unified-entry` **并存**；凡涉及**当前仓库**内实现、配置、排错与 Flow2Spec 知识路由的回答，**以本条约束「何时必须先读磁盘上的知识库」为准**。统一入口中的读取顺序在**满足本条之后**继续适用。
+
+## 适用范围（须执行首读）
+
+用户问题若可能依赖下列任一类信息，即视为「须先走知识库」：
+
+- 当前仓库中的**实现代码**、目录与模块约定、构建/部署/运行时行为、`.Knowledge/`、`f2s-*` 技能、`manifest-routing` 所描述的主题路由等；
+- 用户未明确声明「与当前仓库无关」、但语境明显依赖本仓库事实时。
+
+## 硬约束：首工具调用
+
+在给出实质性结论或修改建议之前：
+
+1. **在本轮用户消息下**，若尚未用工具读取过 **`.Knowledge/manifest-routing.json`**，则 **第一个** 使用的代码/知识库类工具 **必须** 为：
+
+   `Read` → 路径 **`.Knowledge/manifest-routing.json`**（项目根相对路径，与统一入口一致）。
+
+2. 读完 manifest 后，再按 `taskToTopicRules` / `matcherPath` **按需** `Read` **单个** matcher 分片与 **`.Knowledge/topics/<topic>.md`**（及 `topicDependencies`），然后才允许对 **除 `.Knowledge/` 以外的业务源码路径** 使用 `SemanticSearch`、`Grep` 或 `Read`。
+
+3. **禁止**：在未执行步骤 1 的情况下，用「凭记忆/凭训练数据」直接断言本仓库特有的路径、配置或行为；若 manifest 或 topic 已明确覆盖，**须以 KB 为准**，源码用于印证或补全 KB 未写细节。
+
+4. **回答末尾（简短一行即可）**：注明本轮依据的 KB 路径（例如「已读 manifest + `topics/<topic>.md`」）；若 manifest 无命中且已读 `fallbackTopic` 对应 topic，写明「走 fallback 分诊」。
+
+## 可跳过首读（极少数）
+
+- 用户仅询问 **IDE/编辑器本身**用法、且与当前仓库目录无关；
+- 用户给出 **绝对路径 + 明确指令**（例如「只把该行改为 x」）且与业务知识无关的纯机械编辑；
+- **同一会话内**已对当前工作区执行过 `Read(".Knowledge/manifest-routing.json")` 且用户未要求「重新路由/全量检查」的**直接续问**：可在回答首句写「manifest 已读本会话，沿用上次路由」，**不再重复 Read** manifest。
+
+## 知识缺口与下钻源码（防「grep 死循环」）
+
+与 **`f2s-flow2spec-unified-entry`** 中 **「知识缺口与对策」** 一致；命中 **1b（命中但上下文不够）** 或 **2（库里没有对应文档）** 时，还须遵守：
+
+1. **先对用户说明，再扩工具**：在已读 `manifest-routing.json` 与应读的 `topics/*.md`（及依赖 topic）之后，若仍**无法仅凭 KB** 精确回答用户问题，**必须先**用自然语言说明：**已读哪些 KB 路径**、**仍缺哪类信息**、**你打算只读哪 1～2 个源码文件**或**请用户补哪篇文档**；不得沉默地连续堆叠「再找入口」式探索。
+2. **探索次数上限**：在未向用户发出上述缺口说明前，**禁止**连续发起 **4 次及以上**仅以扩大搜索面为目的的 `Grep` / 无明确目标的 `SemanticSearch`。说明并获用户默许（或问题明确要求追到底）后，再有序下钻。
+3. **单点下钻优先**：若仅需确认行为细节，应优先 **Read 一个**与问题最相关的实现文件并据此作答；**禁止**为同一子问题在无新假设的情况下链式深入第三方依赖目录中多文件，除非用户明确要求通读依赖。
+
+### 缺口闸门（针对「规则有写、执行跳过」）
+
+当且仅当已读完 **manifest + 应读 topics** 后，仍判定为 **1b / 2**、且**下一步**要使用指向**业务源码树**（非 `.Knowledge/`）的 `Read` / `Grep` / `SemanticSearch` 时：
+
+- **必须先**产出一段**终端用户可见**的自然语言（可与简短结论同屏），且至少包含：**(a)** 已读的 KB 路径；**(b)** 缺口一句（topic 缺哪类信息或库中无文档）；**(c)** 拟打开的 **1～2 个具体文件路径**或征询用户是否先补 `req-docs`/stock-docs。
+- **禁止**在**从未**输出过满足 (a)(b)(c) 的可见说明的情况下，连续发起多轮仅用于「再找入口」的源码侧工具调用（此即「规则已写但未先做缺口说明」的执行层遗漏）。
+- 下钻后给出**行为、状态码、错误文案**等事实时，**须以本次实际读到的源码与契约为准**；不得凭推测或与当前仓库无关的外部项目经验填写。
+
+上述 (a)(b)(c) 与 **`f2s-flow2spec-unified-entry`** 表中「向用户要文档或路径」「明确承认知识库无覆盖」**同一语义**：不得用「已在内心判定为 1b」代替**已对用户写出**的缺口说明。
+
+### 与执行环境的交互（权限、确认类噪音）
+
+在带沙箱或权限门控的 IDE 中，**短时间连续**发起多轮 `Grep` / `SemanticSearch` / 大范围读盘，常表现为**对同类权限或确认的重复询问**。这与 Flow2Spec 规则是否写明无直接关系，多由**探索链过长、无停止条件**放大。遵守本节「缺口闸门」「探索次数上限」与下文「检索体积与作答节奏」、优先单文件 `Read`，可显著减少此类打扰。
+
+## 检索体积与作答节奏（降低多轮扫描、体感变慢）
+
+本节针对 **Codex / 终端 IDE** 等环境中「一次问答多轮 `grep`、输出量巨大、总耗时长」的常见根因，与「首读 manifest」**不冲突**：仍须先 `Read` manifest，再收窄搜索面。
+
+1. **`Grep` / 文本搜索范围**：在已读命中 topic 且其中给出**具体文件或目录路径**时，搜索**不得**大于该路径；无路径时再缩到**单一**最可能目录（如 `src/utils/` 或 `src/functions/<活动目录>/`）。**禁止**在无用户明确要求「全仓检查」且未满足统一入口「全量补检索触发门槛」时，对 **`src/` 根、`src/functions` 全域、`.Knowledge` 等多处并列**做一次超大范围扫描。
+2. **大命中量时**：若单次搜索命中行数明显过多，应**停止扩大关键词或路径**，改为优先 **`Read` topic 或 stock-docs 已点名的 1～2 个主文件**；仍不足再缩小模式或目录做**第二次**窄 `Grep`。
+3. **两阶段作答**：用户未明确要求「列出全部实现细节 / 通读依赖 / 审计全链路」时，在 manifest + 应读 topics（及 stock/req 中 topic 已指明的材料）已足以形成结论时，**可先输出对用户有用的短答案**；实现细节、额外文件清单仅在用户追问依据或「展开」时再下钻，**禁止**仅为自验完备而拉长探索链。
+4. **避免重复读盘**：本会话内已对某文件做过**全文** `Read` 且无新用户指令或新假设时，**禁止**再次对该文件发起等价全文 `Read`。
+
+## 对 Agent 自检
+
+若你发现自己在回答当前仓库相关问题时尚未 `Read` manifest，**须立即停止补写**，先 `Read` manifest 与命中 topic，再更正或续答。

package/templates/rules/f2s-stock-docs-vs-req-docs.mdc

@@ -0,0 +1,16 @@
+---
+description: 区分 .Knowledge/stock-docs（存量上下文）与 .Knowledge/req-docs（需求与技术方案）；禁止混用路径与链出目标
+globs:
+  - "**/.Knowledge/stock-docs/**/*.md"
+  - "**/.Knowledge/req-docs/**/*.md"
+alwaysApply: false
+---
+
+> **唯一长文**：本文件为 **stock-docs-vs-req-docs** 的完整约定。`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-stock-docs-vs-req-docs.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。
+
+# stock-docs 与 req-docs
+
+- **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-ctx-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-doc-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。
+- **`.Knowledge/req-docs/`**：需求澄清、技术方案（前后端/数据/任务等）、`f2s-doc-pdf` 输出的「按方案实现」MD；`implement-tech-design` 的触发范围为 `.Knowledge/req-docs/**/*.md`。
+
+完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。