@accelerator-mzq/forge 1.4.0

package/dist/core/templates/commands/upgrade.md

@@ -0,0 +1,58 @@
+---
+description: 调 forge upgrade CLI(legacy adapter 清理 + marker resign)
+argument-hint: '[--resign-markers <changeId>] [--recover] [--gc] [--dry-run]'
+---
+
+# /forge:upgrade
+
+包装 `forge upgrade` CLI(v0.3 / plan-9j 落地)。
+
+## 用法 / 选项(v6 MINOR 4:option flag 形态,不是 subcommand)
+
+- `forge upgrade`(无 flag,沿 v0.3):清理 legacy v0.2 harness adapter 产物
+- `forge upgrade --resign-markers <changeId>`(plan-9j 新增 option):升级 v0.4 marker 到 v1.0 schema
+
+## --resign-markers 用法(plan-9j Task 2 落地)
+
+```bash
+forge upgrade --resign-markers add-oauth-refresh
+```
+
+行为:
+
+- **S 简码** → 自动映射 CRITICAL
+- **L 简码** → 自动映射 SUGGESTION
+- **C 简码** → 写 pending file 到 `.evidence/pending-acks/`,exit 1 + 提示走 `forge ack confirm`
+- **不自动填空** verify_findings / pause_decisions / process_evidence(违反 AI 反向加固)
+- 改标 `process_evidence_unavailable_legacy: true` meta 字段
+- 写 `ack-log.jsonl` action=resign 行
+
+退出码(沿 master §3.12.3):
+
+- 0:全部 marker resigned 或已是 v1.0
+- 1:部分需 C 简码 confirm / 阶段事务失败
+- 2:CI 模式拒绝(env CI=true)
+
+## C 简码迁移协议(完整流程)
+
+C 简码(clarification)不自动映射(沿 design §2.3.5):用户必须判断目标 severity:
+
+1. 跑 `forge upgrade --resign-markers <changeId>` — 若含 C 简码,exit 1 + 写 pending file
+2. 跑 `forge ack confirm <changeId> <findingId> --target-severity WARNING|SUGGESTION`(或走 `/forge:ack-confirm` slash)
+3. 重跑 `forge upgrade --resign-markers <changeId>` 完成 resign
+
+## sunset policy
+
+`process_evidence_unavailable_legacy: true` 在 v2.0 sunset(沿 design §3.4.4.2):
+
+- v1.0 / v1.1:合法
+- v1.2:warning 加强
+- v2.0:拒签,`forge migrate <change-id>` 自动触发 process_evidence 补录
+
+## archive 行为(沿 plan-9j Task 3 / 4)
+
+archive.ts 步骤 3.4 在 evidence 校验之前先跑 legacy-exemption + version-retrograde fence:
+
+- legacy marker 缺 created_by_tool_version 字段或 `<1.0.0` → 走 legacy 路径(13 不变量精确豁免)
+- **`legacy=true ⊥ (created_by_tool_version >= 1.0.0 且 resigned_by_tool_version 缺失)`** 互斥(沿 §3.4.4.1 + v6 选项 C resigned-aware):原生 v1.0 marker 不允许 legacy 标记;resigned 后 marker(含 resigned_by_tool_version 字段)允许 legacy + version 共存
+- version retrograde(高版本 → 低版本)→ 拒签(沿 §3.4.4.3)

package/dist/core/templates/commands/verify.md

@@ -0,0 +1,186 @@
+---
+description: 跑 forge validate + verification-before-completion + 三维度分析,产 verify_findings 写入 .verify-passed marker
+argument-hint: '[--change-id <id>]'
+---
+
+You are about to handle `/forge:verify $ARGUMENTS`.
+
+解析:`--change-id <id>` 默认 `forge/changes/` 下唯一未归档的 change;若 >1,**报错并停止**列出选项。
+
+## 步骤
+
+1. **必须调用 `forge:verification-before-completion` skill**(证据先于声称的纪律)。
+
+2. **跑 `forge validate <change-id>`**(plugin helper 走 `${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs validate`),拿到 validate 结果。validate 已产 `automated=true` CRITICAL `finding_hash`(沿 plan-9d Task 4)。
+
+3. **若 validate 失败(exit 1 — CRITICAL findings 存在)**:
+   - 根据失败项构造 verify-failed YAML(`forge/changes/<id>/.verify-failed`):
+     ```yaml
+     schema: forge-verify-failed/v1
+     failed_at: <ISO 8601>
+     reasons:
+       - <每个 CRITICAL finding 的 message>
+     fake_completions: []
+     appended_tasks:
+       - verify-fix-1
+     verify_findings: # plan-9d 新增 — validate CLI 产的 automated CRITICAL finding 直接合并
+       - id: 1
+         dimension: completeness
+         check_type: spec-files-missing
+         severity: CRITICAL
+         automated: true
+         finding_hash: <validate 输出的 hash>
+         evidence: <validate output>
+         recommendation: <validate output>
+         resolved: false
+     ```
+   - **append 修复 task 到 `forge/changes/<id>/tasks.md`**(沿 v0.4 协议)
+   - **不要修改原已勾选 task**(维护 spec §3.3 不变量 2)
+
+4. **若 validate 通过(exit 0)**:
+
+   4.1 **跑用户项目测试** — 读 `forge/config.yaml` 的 `test.test_command`,缺省 `pnpm test`,把 stdout 写到 `forge/changes/<id>/.evidence/test-output.log`,计算 `log_hash = sha256(test-output.log)`。**测试 pass 是 Completeness/task-completion 子项**(plan-9d 三维度协议)。字段路径以代码事实为准(`src/core/schema/types.ts:83` + `src/core/archive/fence.ts:146`)。
+
+   4.2 **三维度分析 — 必须调用 `forge:verifying-three-dimensions` skill**(plan-9d 落地):
+   - **Completeness**:对 spec 每个 Requirement,grep codebase 找实施证据;完全无证据 → 产 CRITICAL `coverage_gap` finding(automated=true,工具可独立验证;沿 §11.1bis — `evidence_missing` 仅指 evidence.log_path 文件缺失,语义不同)
+   - **Correctness**:对 spec 每个 Requirement 定位实施 file:line;WHEN/THEN scenario 覆盖检查 → WARNING/SUGGESTION findings(automated=false)
+   - **Coherence**:design.md `## Decision:` 段比对 codebase;命名 / pattern 比对项目惯例 → WARNING/SUGGESTION findings(automated=false)
+   - **每个 finding 必须填**:id / dimension / check_type / severity / automated / content_hash / git_head / evidence / recommendation / resolved + finding_hash(JCS SHA256 of 8 字段 payload,沿 9a)
+   - **`automated=true` 的 finding 必须由工具或 CLI 计算 finding_hash**(直接 grep 命中数等机器判定);AI 不能伪造此类 finding
+   - **`automated=false` 的 finding 由 AI 产**,需 `forge ack propose` 走两步流程才能降级或带未 ack archive(沿 9a)
+   - **AI 计算 finding_hash 必须用 `forge finding hash` helper**(v6 M-1 修订 + v7 N-1 修订:沿 plan-9d Task 4 step 12-13)— 防止 AI 自实现 JCS 易出错。示例**用 heredoc 避免单引号 shell 破损**(JSON 内换行 / 单引号 / 中文均安全):
+
+     ```bash
+     # 把 8 字段 payload 写成 JSON pipe 给 helper,helper 输出 64-hex finding_hash
+     cat <<'JSON' | forge finding hash
+     {
+       "content_hash": "sha256:abc123...",
+       "git_head": "d4e5f6...",
+       "dimension": "correctness",
+       "check_type": "requirement-mapping",
+       "severity": "WARNING",
+       "automated": false,
+       "evidence": "specs/auth/spec.md Requirement #2 在 src/auth/refresh.ts:42 实现 expiryHours=12,spec 默认 24h",
+       "recommendation": "改 expiryHours=24 或修订 spec"
+     }
+     JSON
+     # 输出:1234abcd5678ef90... (64-hex 裸 hex 沿 9a)
+     ```
+
+     **关键约束**:
+     - **用 `<<'JSON'` heredoc(单引号 quoted)**:JSON 内部含单引号 / `$` / 反引号 / 中文均不会被 shell 解析(v7 N-1 修订:沿 bash heredoc quoted delimiter convention)
+     - **不能多传 extra keys**(id / resolved / finding_hash 自身)— helper 内部已显式构造 8 字段,extra keys 会被丢弃,但 AI 应该传干净 payload 避免混淆
+     - **JSON 内换行用真实换行**(不写 `\n`)— heredoc 保留原样换行;若 evidence/recommendation 内文要含 `\n` 字面值则写 `\\n` 双反斜杠(JSON 串 escape)
+
+       4.3 **写 `forge/changes/<id>/.verify-passed` YAML**(沿 design §2.2.5 schema superset):
+
+     ```yaml
+     schema: forge-verify/v1
+     verified_at: <ISO 8601>
+     verified_by: ai-agent
+     tasks_hash: <sha256(tasks.md 已勾段)>
+     content_hash: <sha256(proposal+specs+design)>
+     evidence:
+       - scenario_id: project-tests
+         test_command: <config.yaml 的 test_command>
+         test_file: <实际跑的测试范围>
+         log_path: ./.evidence/test-output.log
+         log_hash: <log_hash>
+         pass: true
+     verify_findings: # plan-9d 新增 — validate CLI 自动 CRITICAL + skill 产 WARNING/SUGGESTION 合并数组
+       - id: 1
+         dimension: completeness
+         check_type: spec-coverage
+         severity: WARNING
+         automated: false
+         content_hash: <sha256>
+         git_head: <40-hex>
+         evidence: 'specs/auth/spec.md Requirement #2 在 src/auth/refresh.ts:42 实现 expiryHours=12,spec 默认 24h'
+         recommendation: '改 expiryHours=24 或修订 spec'
+         resolved: false
+         finding_hash: <sha256>
+         severity_acked_by: null # WARNING 必须 ack 才能 archive(在 archive 阶段走 ack)
+         severity_acked_at: null
+       # ... 其他 finding
+     pause_decisions: # apply 阶段累积的 pause 决策在写本 marker 时一并迁移(本 fix 补 lifecycle 注;沿 commands/apply.md "Marker 持久化" 段)
+       - id: 1
+         # ... 完整 schema 见 commands/apply.md "Marker 持久化" 段
+     ```
+
+     4.3a **(本 fix 补缺):调 forge evidence record-verify 记录 verify 事件证据到 staging**
+
+     主代理在写完 .verify-passed YAML 后、freeze 之前,**必须**先调 record-verify 写 staging:
+
+     ```bash
+     forge evidence record-verify <changeId> --task-refs <list> --scope <type> --report <path>
+     ```
+
+     这一步把 verify 事件(测试 pass/fail + 三维 findings 总览)写入 `.evidence/process-evidence.staging.yaml`,**freeze 必须前置 staging 才有 source 可以凝固**(沿 `src/cli/commands/evidence.ts:348/639`;helper list 权威 `commands/apply.md:179-182`)。
+
+     若漏调 record-verify 直接 freeze → exit 1 + 提示 "staging file not found ... 必须先调 forge evidence record-\*"(代码事实 `evidence.ts:639`)。
+
+     4.4 **(plan-9g 新增):调 forge evidence freeze 凝固 process_evidence**
+
+     主代理在 4.3a record-verify 后,**必须**调:
+
+     ```bash
+     forge evidence freeze <changeId> --kind verify
+     ```
+
+     freeze 子命令做:
+     1. 读 `.evidence/process-evidence.staging.yaml` + 校验 staging_hash
+     2. 复制三数组(tdd_event_chain / verify_invocations / subagent_review_chain)到 marker.process_evidence
+     3. 写 marker.process_evidence_staging_hash + ack_log_tail_hash + ack_log_entry_count(五源 cross-check 用)
+     4. 算 freeze-time WARNING(不变量 7 + 10)→ 转 VerifyFinding 写 marker.verify_findings
+     5. 若 CRITICAL 11/12(tdd_exemption 缺 ack / mode 缺 ack)→ exit 1 + 提示先跑 forge ack
+     6. transaction(tmp + rename atomic)落 marker
+
+     详细 process_evidence 协议见 `skills/process-evidence/SKILL.md`。
+
+     4.5 **若产任何 WARNING + resolved=false**:提示用户 — archive 阶段必须先 `forge ack propose <finding-id>`(沿 9a 两步流程),否则 archive fence 拒签。
+
+     4.6 **若产任何 automated=true CRITICAL + resolved=false**:**不能 archive**(沿 design §2.2.4 fence)— 必须先实际修复让 finding resolved=true(改 code + 重跑 verify),不允许 ack 降级。
+
+## 禁止行为
+
+- 不允许在 verify 失败时回去把已勾 task 改回 `[ ]`(违反 spec §3.3 不变量 2)
+- 不允许跳过证据 log 写入(verification-before-completion 要求证据先于声称)
+- 不允许 pass=true 但 evidence 为空(archive 校验会拒绝)
+- **不允许跳维度**(沿 plan-9d skill 红旗清单)— Completeness + Correctness + Coherence 三维度必须全跑,即使测试 pass
+- **不允许伪造 automated=true finding**(沿 design §2.3.3 critical_candidate 协议)— automated=true 的 finding 必须由工具/grep 机器判定,不能 AI 自决
+- **不允许 vague recommendation**("consider reviewing X" 类)— 必须给 file:line 或 spec:Requirement-id 具体证据(沿 plan-9d skill `## forge-specific 反向加固` §2)
+- **不允许在 .verify-passed 写 severity_acked_by = "ai-agent" 自 ack**(必须走 `forge ack propose` 两步流程,沿 9a)
+
+## (可选)Stage extensions hook — Tier 1 Claude Code only
+
+> codex review 集成。AI 主代理在本 stage(`verify`)跑多轮收敛协议。
+> Tier 2/3(Codex/OpenCode)见 [`docs/stage-extensions.md §未来 Tier 2/3 集成`](../docs/stage-extensions.md#未来-tier-23-集成)。
+
+**Step A — 检查是否启用**:读 `forge/config.yaml#stage_extensions.verify`。无该字段 / 数组为空 / 全部 entry `enabled: false` → **跳过本段,流程结束**。
+
+**Step B — 对每个 `enabled` entry 跑多轮收敛 loop**:
+
+初始化 `round = 1`、`threadId = ''`、`roundHistory = []`、`roundLimit = null`(F1-v8 fix:`roundLimit` **不从 config 文件读** —— effective convergence 由 runner 输出,见 Step 3。AI 协议不碰 config 文件解析 / deep-merge,单一数据源是 runner JSON)。循环:
+
+1. **跑单轮 runner**:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions run \
+     --stage verify --change-id <change-id> --extension <entry-name> \
+     --round <round>${threadId:+ --thread-id $threadId}
+   ```
+2. **解析 stdout JSON 的 `kind`**:
+   - `converged` → 该 entry 收敛完成,**break loop**(codex 输出 verbatim 透传给用户)
+   - `failed` / `config_error` / `no_extension` → 该 entry 放弃,**break loop**(loose,不阻塞主流程)
+   - `unconverged` → 继续 3
+3. **从 unconverged JSON 取状态**(F1-v8 fix:effective config 来自 runner 输出,runner 内 `validateStageExtensionsConfig` 已 normalize):
+   - `roundHistory.push({ round, block_count: <blockFindings.length> })`;`threadId = <JSON.threadId>`;codex finding verbatim 透传给用户
+   - 首轮:`roundLimit = <JSON.effectiveConvergence.max_rounds>`(后续轮 `roundLimit` 已设,不覆盖 —— 选项①的 `roundLimit += N` 增量须保留)
+4. **若 `round >= roundLimit`**(F2-v7 fix:用可增长的 `roundLimit`):
+   - 若 `<JSON.effectiveConvergence.max_rounds_on_exceed>` 为 `force_end` → 把 blockFindings 写 `forge/changes/<id>/.evidence/codex-pending-findings.yaml`(backlog),**break loop**
+   - 否则跑 `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs" stage-extensions analyze-trend --history '<roundHistory JSON>'` 拿 TrendAdvice,再 `AskUserQuestion` 三选项(默认推 `TrendAdvice.recommended_option`):**①再跑 N 轮**(F2-v7 fix:读用户输入的 `N`,执行 `roundLimit += N`,然后 `round++` 继续 loop —— 后续 `round >= roundLimit` 判定按新上限走,不会立刻又进 Step 4)/ **②放弃 codex**(break loop)/ **③接受当前**(blockFindings 写 backlog,break loop)
+5. **否则(`round < roundLimit`)**:`AskUserQuestion` 三选项(默认推 `<JSON.userInteraction.block_unconverged>`):
+   - **①auto_fix** → 用 `Task` 工具 dispatch fresh fix subagent 修 blockFindings → `round++`,继续 loop
+   - **②manual_fix** → 等用户改完 → `round++`,继续 loop
+   - **③give_up** → break loop
+
+**Step C — loose**:本段任何步骤(runner 调用 / AskUserQuestion / fix dispatch)失败都**不阻塞主流程 fence**。runner 永远 exit 0;AskUserQuestion harness 不支持时降级终端 prompt。

package/dist/core/templates/index.d.ts

@@ -0,0 +1,3 @@
+export { SKILL_NAMES, loadSkill, loadAllSkills, loadAllSharedDocs, type SkillName, type LoadedSkill, } from './skills/index.js';
+export { COMMAND_NAMES, loadCommand, loadAllCommands, type CommandName, type LoadedCommand, } from './commands/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/templates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/templates/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,WAAW,EACX,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,aAAa,EACb,WAAW,EACX,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/core/templates/index.js

@@ -0,0 +1,5 @@
+// templates 模块顶层导出 — Plan 4
+// 把 skills + commands 两个 sub-registry 聚合成单一入口
+export { SKILL_NAMES, loadSkill, loadAllSkills, loadAllSharedDocs, } from './skills/index.js';
+export { COMMAND_NAMES, loadCommand, loadAllCommands, } from './commands/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/templates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/templates/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,8CAA8C;AAE9C,OAAO,EACL,WAAW,EACX,SAAS,EACT,aAAa,EACb,iBAAiB,GAGlB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,aAAa,EACb,WAAW,EACX,eAAe,GAGhB,MAAM,qBAAqB,CAAC"}

package/dist/core/templates/skills/_shared/scope-category-guidance.md

@@ -0,0 +1,40 @@
+---
+title: Scope Category Guidance
+description: AI 判定指引 — 找到一个"未实施项",该写到哪里(SUGGESTION / Future Work / Out of Scope / Non-Goal)
+source-of-truth: forge v1.0 design §2.6.6
+---
+
+# Scope Category Guidance
+
+> 此文档是 `skills/_shared/` 下的共用 reference,由 `forge:receiving-code-review` / `forge:verifying-three-dimensions` / `forge:exploring` 三 skill 引用。不要把这表抄到各 skill — 集中维护避免漂移。
+
+## 决策表(沿 design §2.6.6)
+
+当你识别出一个"未在本 change 实施的事项",按下表四选一,不要默认塞 SUGGESTION:
+
+| 状态                           | 写到                                                                                    | 语义                               | 判定指引(关键词)                                                                                       |
+| ------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **应在本 change 做但低优先级** | `verify_findings` / `review_outcomes` 的 `SUGGESTION` finding                           | 本 change 内的 nice-to-have,可不做 | "可定位 + 可修复 + 不做也不影响本 change 核心目标"(例:补一处 log message 措辞 / 加一个 edge case 测试) |
+| **本 change 不做,未来可能做**  | `design.md` `## Future Work {#forge-future-work}` 段的 `forge-scope-entries/v1` YAML 块 | 跨 change 长期 backlog             | "实施会扩 scope,但目标方向一致"(例:本 change 加 OAuth 基础,refresh-token-grace-period 留 future-work)  |
+| **本 change 不做,原则反对做**  | `proposal.md` `## Non-Goals {#forge-non-goals}` 段的 YAML 块                            | 反目标                             | "实施会偏离项目方向 / 违反核心约束"(例:加密产品不接受"明文密码可选项")                                 |
+| **本 change 不做,无强烈意见**  | `proposal.md` `## Out of Scope {#forge-oos}` 段的 YAML 块                               | 中性 out-of-scope                  | "明显不属于本 change 但未来可能做也可能不做"(例:本 change 加 password-reset,SSO/SAML 不属于但不反对)   |
+
+## 常见误判 → 修正
+
+| AI 倾向                                     | 修正                                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 把所有"不做"塞 SUGGESTION 持挂              | SUGGESTION 应**只**用于"本 change 内 nice-to-have";跨 change 项必须走 out-of-scope/future-work/non-goal |
+| 把"未来可能做"标 Non-Goal                   | Non-Goal 是**反对**做;不确定的项应走 Future Work 或 Out of Scope                                        |
+| 给 `## Out of Scope` 段填一句话不写 YAML 块 | OK — 但若有具体项,**必须**写 forge-scope-entries/v1 YAML 块带 reason(沿 plan-9b §2.6.3 reason 必填)     |
+| 编 entry 的 `reason` 为空 / 写"未来再说"    | reason 是 forge 比 OpenSpec 强制升级的字段;空 reason 会被 `forge validate` 拒签为 CRITICAL              |
+| 用本地化标题就改 anchor ID                  | **anchor ID 是契约**,标题文字可改(`## 不做项 {#forge-oos}`),但 `{#forge-oos}` 不可改                    |
+
+## Fence 反向加固(`/forge:archive`)
+
+archive 阶段若发现 SUGGESTION > 5 项 或 SUGGESTION 中含关键词(`future` / `later` / `outside scope` / `未来` / `后续` / `超出` / `另外`),给 deprecation warning 提示考虑推到 `## Future Work` / `## Out of Scope`。**仅 warning,不阻断**(沿 design §2.3 SUGGESTION 不要求 ack)。
+
+## Cross-reference
+
+- 数据 schema:`src/core/schemas/scope-entries.ts`(`forge-scope-entries/v1`)
+- 锚点契约:`{#forge-oos}` / `{#forge-non-goals}` / `{#forge-future-work}`(沿 design §2.6.3)
+- 跨 change 扫描:`forge scope scan-archived-followups <change-id>`(沿 design §2.6.5)

package/dist/core/templates/skills/brainstorming.md

@@ -0,0 +1,161 @@
+---
+name: forge:brainstorming
+description: You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Pre-flight check — Git base assumption (P2 fix from v0.2 fixture testing)
+
+**Before starting brainstorming flow**, verify the repo has a git base ready for `Write draft` step (Step 5):
+
+```bash
+git rev-parse HEAD 2>/dev/null && test -f .gitignore
+```
+
+If either fails(no commits yet, or no `.gitignore`):
+
+- **Do NOT silently commit the draft later**. Ask the user explicitly first:
+
+  > "我注意到这是空 git repo / 缺 `.gitignore`。要不要先 `git init` + 加 `.gitignore`(标准 Node/Python/etc patterns)+ first commit 再继续 brainstorming?这样 draft commit 才有 base。"
+
+- 用户确认 → 帮加 `.gitignore` + `git init`(若需)+ first commit
+- 用户拒绝 → 跳过 Step 5 commit,只 Write draft 但不 commit;提示用户"draft 已写但未 commit,完成后请手动 commit 或先建 git base"
+
+This pre-flight prevents the v0.2 fixture-test P2 issue: brainstorming silently committing draft on a half-initialized repo.
+
+---
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Pre-flight git base check** — see above section; gate before proceeding
+2. **Explore project context** — check files, docs, recent commits
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write draft** — save to `forge/drafts/YYYY-MM-DD-<topic>.md` and commit (skip commit step if pre-flight #1 declined). Do NOT save to forge/specs/(specs/ 仅由 archive 内部 sync 写入,见 spec §3.4).
+7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+8. **User reviews written draft** — ask user to review the draft file before proceeding
+9. **Transition to implementation** — invoke forge:writing-plans skill via /forge:propose <change-id> --from-draft <date>-<topic>
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write draft" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews draft?" [shape=diamond];
+    "Invoke forge:writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write draft" [label="yes"];
+    "Write draft" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews draft?";
+    "User reviews draft?" -> "Write draft" [label="changes requested"];
+    "User reviews draft?" -> "Invoke forge:writing-plans skill" [label="approved"];
+}
+```
+
+**The terminal state is invoking forge:writing-plans via /forge:propose.** Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is forge:writing-plans.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own draft → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated draft to `forge/drafts/YYYY-MM-DD-<topic>.md`
+  - (User preferences for draft location override this default)
+- Commit the draft document to git
+
+**Spec Self-Review:**
+After writing the draft document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written draft before proceeding:
+
+> "Draft written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke the forge:writing-plans skill via /forge:propose <change-id> --from-draft <date>-<topic> to create the change proposal + implementation plan. Do NOT invoke any other skill.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+<!-- Visual companion 在 forge v0.1 不提供,brainstorming 全程在终端做。 -->