[tech] 🚀 feat(skills): 主链无二次确认 + Core-only 更新自动代跑

.Knowledge/index.md

@@ -50,7 +50,7 @@
 
 ## 命中与执行（与统一入口一致）
 
-- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中,详见 `topics/kb-routing-summary.md`)。
+- **路由**：`taskToTopicRules` 给出任务 → 主题集合；**关键词**在 matcher 分片(`includeAny` / `includeAll` 资格门 + `excludeAny` / `excludeAll` 否决门；否决优先于 `task` 精确命中)。
 - **依赖**：命中主主题前，按 `topicDependencies` 先读依赖主题。
 - **兜底**：`fallbackTopic` 指向分诊主题（如 `fallback-triage`），仅低置信度上下文，**不得**当作最终命中直接改代码。
 - **执行链**：`match → expand → verify → act`；`expand` 须含依赖展开，并保留次高候选做校验。

.Knowledge/manifest-routing.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.2",
+  "version": "3.7.0",
   "knowledgeRoot": ".Knowledge",
   "matcherKey": "matcherId",
   "sourceOfTruth": ".Knowledge/manifest-routing.json",
@@ -211,7 +211,7 @@
       "summary": "初筛 summary 与 matcher 分片 4 字段(资格/否决门)语义"
     }
   ],
-  "projectRev": 2,
+  "projectRev": 3,
   "pkgRev": 3,
   "topicMetadata": {
     "implement-tech-design": {

.claude/hooks/f2s-update-check.js

@@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j
 const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json');
 const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__';
 const PACKAGE_NAME = '@double-coding/flow2spec-core';
-const GENERATED_CORE_VERSION = '3.7.2';
-const GENERATED_TEMPLATE_VERSION = '3.6.2';
+const GENERATED_CORE_VERSION = '3.8.0';
+const GENERATED_TEMPLATE_VERSION = '3.7.0';
 
 function readJson(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }

.codex/hooks/f2s-update-check.js

@@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j
 const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json');
 const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__';
 const PACKAGE_NAME = '@double-coding/flow2spec-core';
-const GENERATED_CORE_VERSION = '3.7.2';
-const GENERATED_TEMPLATE_VERSION = '3.6.2';
+const GENERATED_CORE_VERSION = '3.8.0';
+const GENERATED_TEMPLATE_VERSION = '3.7.0';
 
 function readJson(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }

.cursor/hooks/f2s-update-check.js

@@ -9,8 +9,8 @@ const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.j
 const CACHE_FILE = path.join(process.cwd(), '.Knowledge', 'update-check.json');
 const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__';
 const PACKAGE_NAME = '@double-coding/flow2spec-core';
-const GENERATED_CORE_VERSION = '3.7.2';
-const GENERATED_TEMPLATE_VERSION = '3.6.2';
+const GENERATED_CORE_VERSION = '3.8.0';
+const GENERATED_TEMPLATE_VERSION = '3.7.0';
 
 function readJson(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }

packages/core/templates/en-US/hooks/f2s-update-check.js

@@ -93,17 +93,24 @@ function buildNotice(state) {
     return [
       '[flow2spec/agent-instruction] At the start of this response, relay this update notice to the user:',
       '',
-      `📦 [flow2spec] Project "${project}" has a template update (${versionSummary}).`,
+      `📦 [flow2spec] Project "${project}" has a template update (${versionSummary}). Template changes affect the knowledge-base topic layout and require user confirmation before proceeding.`,
       '',
-      '[flow2spec/agent-instruction] You may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep), then `flow2spec init <initialized agents>`. After init, read `.Knowledge/manifest-routing.json`: if projectRev equals pkgRev, delete `.Knowledge/update-check.json`; otherwise continue with f2s-kb-upgrade from step 2c.',
+      '[flow2spec/agent-instruction] Recommended flow (do NOT skip user confirmation):',
+      '1. Ask the user whether to run `flow2spec update --cli` + `flow2spec init <initialized agents>` on their behalf (if the global CLI is missing, fallback to `npx @double-coding/flow2spec update --cli`).',
+      '2. On user consent: run them; after init, read `.Knowledge/manifest-routing.json` — if projectRev equals pkgRev, delete `.Knowledge/update-check.json` and stop; otherwise invoke the f2s-kb-upgrade skill (may resume from its step 2c).',
+      '3. On user decline: keep the cache untouched and continue the current task.',
     ].join('\n');
   }
   return [
-    '[flow2spec/agent-instruction] At the start of this response, relay this update notice to the user:',
+    '[flow2spec/agent-instruction] At the start of this response, execute the following actions **without asking the user** (Core-only updates do not affect knowledge-base topics):',
     '',
-    `📦 [flow2spec] Project "${project}" has a Core-only update (${versionSummary}); the template version is unchanged.`,
+    `1. Tell the user in one line: "Auto-updating CLI/Core (${versionSummary}); knowledge-base topics are unchanged.";`,
+    '2. Invoke Bash to run `flow2spec update --cli`; if it fails because the global CLI is missing, fallback to `npx @double-coding/flow2spec update --cli`; if that still fails, report the command and error summary in one line and continue the current task without blocking;',
+    '3. On success, invoke `flow2spec init <initialized agents>` (idempotent) to refresh the config-root Hook;',
+    '4. Delete `.Knowledge/update-check.json` afterwards;',
+    `5. Report completion in one line: "CLI/Core updated; Template Version unchanged (v${state.manifestVersion}); continuing the current task."`,
     '',
-    '[flow2spec/agent-instruction] You may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep), then one idempotent `flow2spec init <initialized agents>` to refresh the Hook. Do not enter f2s-kb-upgrade when Template Version is unchanged; delete `.Knowledge/update-check.json` afterwards.',
+    `📦 [flow2spec] Project "${project}" has a Core-only update (${versionSummary}); the template version is unchanged. Template Version is unchanged — **do NOT** enter f2s-kb-upgrade.`,
   ].join('\n');
 }
 

packages/core/templates/en-US/rules/f2s-flow2spec-unified-entry.md

@@ -98,7 +98,10 @@ Each initialized client uses its own startup/update mechanism when supported; th
 **Rule-layer fallback check** (backup for script cache):
 
 1. Read `flow2spec.config.json` -> if `updateCheck.enabled` is not `true`, skip and show no notice.
-2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is on the same local calendar day, do not query npm again. When `coreUpdateAvailable=true`, the agent may run `flow2spec update --cli` (CLI and its pinned Core update in lockstep). If `templateUpdateAvailable=false`, run one idempotent `flow2spec init <initialized agents>` to refresh the Hook, delete the cache, and do not enter `f2s-kb-upgrade`. If `templateUpdateAvailable=true`, update first, run init, then use `projectRev` / `pkgRev` to choose the fast path or full flow. `.Knowledge/manifest-routing.json.version` is Template Version and must not be compared directly with Core Version.
+2. Read `.Knowledge/update-check.json` -> if the file exists and `checkedAt` is on the same local calendar day, do not query npm again. Handle two scenarios separately:
+   - **`coreUpdateAvailable=true` and `templateUpdateAvailable=false`** (Core-only update): the agent **must actively run** `flow2spec update --cli` (fallback to `npx @double-coding/flow2spec update --cli` if the global CLI is missing; if that still fails, report in one line and continue without blocking) + one idempotent `flow2spec init <initialized agents>` at the start of this turn to refresh the Hook. Before running, tell the user in one line "Auto-updating CLI/Core; knowledge-base topics are unchanged". Afterwards delete `.Knowledge/update-check.json`, **do NOT** enter `f2s-kb-upgrade`, and **do NOT ask the user for confirmation** (Core-only updates do not affect knowledge-base topics).
+   - **`templateUpdateAvailable=true`** (Template changed; Core may also have changed): the agent **must** relay the notice at the start of the turn **and ask the user whether to run** update + init. On consent, run `flow2spec update --cli` + init, then use `projectRev` / `pkgRev`: equal -> delete the cache and stop; unequal -> invoke the `f2s-kb-upgrade` skill (may resume from its step 2c).
+   - `.Knowledge/manifest-routing.json.version` is Template Version and must not be compared directly with Core Version.
 3. If neither of the two steps above skipped the check: run the update-check script under the current agent configuration root (Claude: `node .claude/hooks/f2s-update-check.js`; Cursor: `node .cursor/hooks/f2s-update-check.js`; Codex: `node .codex/hooks/f2s-update-check.js`) and parse JSON from stdout:
    - If it contains `hookSpecificOutput.additionalContext`: **tell the user** that content and follow its separate Core-only or Template-update instructions.
    - If there is no output or parsing fails: stay silent.

packages/core/templates/en-US/rules/f2s-implement-tech-design.md

@@ -94,9 +94,19 @@ If `changeTracking.implement: true`, after outputting the task list, write this
 - Whenever work corresponding to an implementation task-list item is completed, use `Edit` **in the same session** to update the corresponding `[ ]` -> `[x]` in `.task/active/<task-name>/task.md`. Do not defer this to closing, and do not replace disk updates with verbal completion claims (see `f2s-task` "During execution" and "Interruption and session end").
 - Whenever an item appears during execution that **must be done by the user** (database changes, environment configuration, etc.), append it **in the same session** to `.task/active/<task-name>/user-todos.md` (see `f2s-task` "user-todos.md").
 
-### Step 3: Ask Pre-Implementation Questions (Mandatory; Do Not Skip)
+### Step 3: Ask Pre-Implementation Questions (Conditional; Skipped by Default)
 
-Before coding, list all unclear items at once and ask the user to confirm. Common questions:
+**Default**: do not stop to ask; proceed directly to Step 4. Items not clearly defined in the design are implemented with reasonable defaults or placeholders and marked as "requires user confirmation" in the Step 5 pending list.
+
+**Trigger conditions** (any one match causes a single stop to list open questions and wait for the user before continuing):
+
+- The design text contains **≥ 3** explicit "undecided" markers such as `待定 / 待确认 / TBD / \?\?\?`;
+- Key contract sections of the design are **entirely missing** (not merely "insufficiently detailed") — for example, the design references APIs but has no API-signature section at all, references data but has no data-model section at all, or references a state machine but has no state list at all;
+- The user explicitly says a stop phrase such as "only list the tasks / don't rush the implementation / let me review the list first / discuss the plan first".
+
+When triggered, list 3–6 open questions that most affect where implementation lands (draw from the common items below), and ask the user to confirm all of them at once. When not triggered, **do NOT ask** — proceed directly to Step 4.
+
+**Common question items** (pick from these when a trigger condition is met):
 
 - **Scope and acceptance**: what must be delivered in this turn, and what is explicitly out of scope;
 - **Technical boundary**: which module/side to implement in (frontend, backend, script, data task, etc.);
@@ -105,8 +115,6 @@ Before coding, list all unclear items at once and ask the user to confirm. Commo
 - **Flowchart gaps**: branch conditions, failure fallback, timeout and retry strategy;
 - **Release constraints**: whether routing, permissions, scheduling, and deployment steps are ready.
 
-If the user does not answer an item, implement using a reasonable default or placeholder and mark it as "requires user confirmation" in the pending list.
-
 ### Step 4: Implement According to the Task List
 
 Trim the order according to the design and the actual project. Recommended sequence:
@@ -139,7 +147,7 @@ Requirements: reuse existing dependencies and wrappers; match project naming, di
 ## 5. Constraints and Summary
 
 - PDFs must be converted to MD before entering the implementation flow.
-- Do not skip step 2.5 (task list) or step 3 (pre-implementation questions) and code directly.
+- Do not skip step 2.5 (task list); step 3 is conditional (skipped by default, and only triggers a single stop when an ambiguity threshold is hit).
 - If `changeTracking.implement: true`: do not skip step 2.6 (write back `task.md` checkboxes as implementation progresses and append `user-todos.md`); archiving must satisfy the `f2s-task` archive gate.
 - The output must include a pending list and post-implementation reminder list. If `changeTracking.implement: true`, user-side items in those lists must be synced into `user-todos.md`.
 - Keep the content general. Do not assume a "backend only" scenario; trim implementation objects according to the design's actual scope.

packages/core/templates/en-US/skills/f2s-kb-sync/SKILL.md

@@ -50,22 +50,55 @@ This skill must not make manual command execution part of the user flow. After t
 
 ### Step 2: Output the "Update Outline" (Required)
 
-The outline must include at least:
-
-1. Sync goal.
-2. Capability list (user-specified / Agent-inferred / merged result).
-3. Information sources.
-4. Proposed file-change list (exact paths).
-5. Topic sync plan: for each capability, state whether it updates an existing topic or creates a new topic, and list topicId, topic file, index row, and manifest/matcher changes. If `topicMetadata` is involved, list candidate `primary` / `tags` / `confidence` and evidence; if evidence is unclear, write "do not classify / do not write for now".
-6. **Stock-doc consolidation plan (hard rule)**: For every topic being "created / updated", check whether its "Detailed background / Related materials / Long-form source / Reference documents" reference slot already has a corresponding `.Knowledge/stock-docs/*_终稿.md`:
-   - **Exists** → reference it directly;
-   - **Missing but the capability being synced is already implemented in code** → the outline **must list** "generate `stock-docs/<capability>_终稿.md`", noting the consolidation sources (the matching `req-docs/*_技术方案.md` + implemented code + clarification doc). Before step 3, this SKILL first triggers `f2s-doc-final` to consolidate (or waits for user confirmation to hand-write), **then** points the topic to the stock-doc;
-   - **Capability is still at the req-docs stage without code** → the topic's "Long-form background" section writes a placeholder "to be generated by `f2s-doc-final` after the code lands". **Do not** list `req-docs/*` in this slot.
-   - Basis: see `rules/f2s-topic-authoring.*` "Directory boundary for long-form background references (hard rule)".
-7. Out-of-scope items.
-8. Prompt to wait for user confirmation.
-
-> Before confirmation, writing any changes is forbidden.
+The outline uses a **3-block main body + collapsible details** structure so the user can grasp "what's in / what's changed / what's out" at a glance and expand details on demand. Goal: **high signal density with visual focus on decision points** (Issue #38).
+
+**Output skeleton** (the Agent fills in the actual content per this structure):
+
+````markdown
+## KB Sync Outline
+
+### 📥 In
+- `<topicId>`: <one-line change description> (→ `.Knowledge/topics/<topic>.md`)
+- **New** `<topicId>`: <capability summary> (→ new topic + matcher + routing entry)
+
+### 🚫 Out
+- <capability / change>: <one-line reason> (e.g., "pure refactor, no new semantics / already covered by another topic / duplicate")
+
+### Continue? (y/n)
+
+<details>
+<summary>Expand details</summary>
+
+**Proposed file changes**:
+- `.Knowledge/topics/<topic>.md`
+- `.Knowledge/index.md`
+- `.Knowledge/manifest-routing.json`
+- `.Knowledge/matchers/<id>.json`
+
+**Topic metadata** (if any):
+- `<topicId>`: primary=`<type>`, tags=`[...]`, confidence=`<manual|inferred>`
+
+**Stock-doc consolidation** (if needed):
+- To generate `stock-docs/<capability>_终稿.md` (sources: `req-docs/<design>.md` + implemented code + clarification doc)
+  Basis: see `rules/f2s-topic-authoring.*` "Directory boundary for long-form background references (hard rule)".
+
+**Information sources**: <user-specified / Agent-inferred / git diff / directory scan>
+
+**Out of scope**: <items deliberately skipped in this run and why>
+
+</details>
+````
+
+**Writing rules**:
+
+- 3-block main body: 📥 In / 🚫 Out / Continue? (y/n); keep each block within **1–5 lines**; scannable at a glance.
+- Details are folded via `<details>` and include: proposed file changes, topic metadata, stock-doc consolidation plan, information sources, out-of-scope items. The fold is a **verifiability** safeguard — it must not be omitted, but it must not occupy the main visual focus either.
+- **The write gate is unchanged**: the user must still reply `y/n` before disk writes (this reform only changes wording, not the gate). Before confirmation, disk writes are forbidden.
+- **Stock-doc consolidation (hard rule)**: When creating or updating a topic, if the "Long-form background / Related materials" reference slot lacks a corresponding `.Knowledge/stock-docs/*_终稿.md`:
+  - Code has landed → list "generate `stock-docs/<capability>_终稿.md`" in the details block; Step 2.5 triggers `f2s-doc-final` to consolidate;
+  - Code not yet landed → the topic's "Long-form background" section writes a placeholder "to be generated by `f2s-doc-final` after the code lands"; **do not** list `req-docs/*` in this slot.
+
+> Before confirmation (y), disk writes are forbidden.
 
 ### Step 2.5: Consolidate Stock-Docs (If Step 2 Listed Any)
 
@@ -115,22 +148,29 @@ After this skill successfully writes to disk (Step 3 actually modified files), t
 
 ## Output Summary Format (Recommended)
 
-```markdown
-## Knowledge-Base Sync Result
+Uses the same **3-block main body + collapsible details** structure as Step 2 outline:
 
-### Confirmed Capability Scope
-- <capability 1>
-- <capability 2>
+```markdown
+## KB Sync Result
 
-### Modified Files
-- .Knowledge/topics/<topic>.md: <change description>
-- .Knowledge/index.md: <change description>
-- .Knowledge/manifest-routing.json: <change description or "unchanged">
-- .Knowledge/matchers/<id>.json: <change description or "unchanged">
-- .Knowledge/stock-docs/<doc>.md: <change description or "unchanged">
+### ✅ Modified
+- `.Knowledge/topics/<topic>.md`: <change description>
+- `.Knowledge/index.md`: <change description>
 
-### Skipped Items
+### ⏭️ Skipped
 - <item>: <reason>
+
+<details>
+<summary>Expand details</summary>
+
+**Other modified paths**:
+- `.Knowledge/manifest-routing.json`: <change description or "unchanged">
+- `.Knowledge/matchers/<id>.json`: <change description or "unchanged">
+- `.Knowledge/stock-docs/<doc>.md`: <change description or "unchanged">
+
+**Capability scope**: <user-confirmed capability list>
+
+</details>
 ```
 
 ## Complex Scenario Example