sillyspec 2.4.0

package/commands/sillyspec/scan.md

@@ -0,0 +1,671 @@
+---
+description: 代码库扫描 — 交互式引导，支持快速/深度扫描和多项目工作区
+argument-hint: "[可选：直接指定区域或模式，跳过交互引导]"
+---
+
+你现在是 SillySpec 的代码库扫描器。
+
+## 参数处理
+
+解析 `$ARGUMENTS`：
+- 空白或未提供 → **交互式引导模式**（逐步询问）
+- 包含具体内容 → **快速模式**，直接执行，跳过询问
+  - 含 `--deep` → 深度扫描
+  - 其他内容 → 当作扫描区域（快速扫描该区域）
+
+**以下流程只在交互式引导模式下执行。如果用户传了参数，跳到对应的 Step。**
+
+---
+
+## 🛑 流程控制（必须先执行）
+
+**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+
+```bash
+sillyspec status --json
+```
+
+**如果 CLI 返回的 phase 不是 "init"，说明已经有扫描数据。** 根据 CLI 返回结果决定：
+
+- `phase: "scan:quick_done"` → 已有快速扫描，建议深度扫描
+- `phase: "scan:resume"` → 深度扫描中断过，调用 `sillyspec check --json` 获取缺失文档列表
+- `phase` 是其他值 → 不需要扫描，提示用户 CLI 建议的下一步命令
+
+**不要自己推断项目状态，以 CLI 返回为准。**
+
+---
+
+## 交互式引导流程
+
+### Step 0: 检查工作区模式
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+如果 config.yaml 存在且包含 `projects` → 工作区模式：
+
+询问用户：
+```
+检测到工作区模式，请选择扫描范围：
+  1) 全部子项目（逐个扫描后生成汇总）
+  2) 指定某个子项目
+  3) 取消
+```
+
+根据选择：
+- 选 1 → 逐个扫描，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`
+- 选 2 → 列出子项目让用户选，只扫选中的
+- 选 3 → 退出
+
+每个子项目的文档存到各自的 `<子项目路径>/.sillyspec/codebase/` 下。
+
+### Step 1: 检查已有文档
+
+```bash
+ls .sillyspec/codebase/ 2>/dev/null
+wc -l .sillyspec/codebase/*.md 2>/dev/null
+```
+
+根据已有文档情况智能提示：
+
+**没有任何文档：**
+→ 不提示，直接进入 Step 2 选择扫描模式。
+
+**已有 3 份（STACK + STRUCTURE + PROJECT）：**
+```
+检测到上次的快速扫描结果。
+→ 输入 1 升级为完整扫描（补充 4 份文档）
+→ 输入 2 重新快速扫描（覆盖现有文档）
+→ 输入 3 跳过，直接开始开发
+```
+
+**已有 7 份完整文档：**
+先检查距上次扫描过了多久：
+```bash
+git log -1 --format="%ci" .sillyspec/codebase/ 2>/dev/null
+git log --oneline --since="上次扫描时间" | wc -l
+```
+
+```
+上次扫描距今 X 天，期间有 Y 个新提交。
+→ 输入 1 刷新（重新扫描全部）
+→ 输入 2 跳过，直接开始开发
+```
+
+**用户选跳过** → 输出"可以开始开发了。建议下一步：`/sillyspec:brainstorm '你的需求'`"然后结束。
+
+### Step 2: 选择扫描模式
+
+```
+请选择扫描模式：
+
+  1. 快速扫描 ⚡
+     读取配置文件和目录结构，约 30 秒
+     生成 3 份文档：技术栈 + 目录结构 + 项目概览
+
+  2. 深度扫描 🔍
+     读取全部源代码并分析，约 2-3 分钟
+     生成 7 份文档：技术栈 + 架构 + 目录结构 + 编码约定 + 集成 + 测试 + 技术债务
+
+  3. 取消
+```
+
+根据选择进入对应的扫描流程。
+
+### Step 3: 选择扫描范围
+
+```
+扫描范围：（留空则扫描整个项目）
+
+  提示：可以输入目录名或模块名，如：
+  - api
+  - src/auth
+  - frontend
+  - 多个区域用空格分隔：api auth
+```
+
+留空 → 全量扫描
+有输入 → 只扫描指定区域
+
+### Step 4: 确认排除目录
+
+```
+以下目录将被排除（不扫描）：
+  node_modules  dist  .git  vendor  build  __pycache__
+  .next  coverage  .nuxt  target
+
+是否需要添加额外的排除目录？（留空跳过）
+```
+
+如果用户输入了额外目录 → 追加到排除列表。
+
+### Step 5: 显示扫描计划并确认
+
+把以上选择汇总，让用户最后确认：
+
+```
+扫描计划确认：
+  模式：深度扫描
+  范围：整个项目
+  排除：node_modules, dist, .git, vendor, build, __pycache__, .next, coverage, .nuxt, target
+
+开始扫描？（输入 y 确认，或修改以上选项）
+```
+
+用户确认 → 执行扫描。用户想改 → 回到对应步骤。
+
+---
+
+## 快速扫描
+
+**只读取入口和配置文件，不读源代码：**
+
+```bash
+# 读取配置文件
+cat package.json 2>/dev/null
+cat tsconfig.json 2>/dev/null
+cat requirements.txt 2>/dev/null
+cat Cargo.toml 2>/dev/null
+cat go.mod 2>/dev/null
+cat pom.xml 2>/dev/null
+cat build.gradle 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+
+# 查看目录结构（排除依赖和构建产物）
+find . -type f -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/build/*" -not -path "*/__pycache__/*" -not -path "*/.next/*" -not -path "*/coverage/*" -not -path "*/.nuxt/*" -not -path "*/target/*" | head -200
+
+# 最近提交
+git log --oneline -20
+```
+
+## 🚨 数据库 Schema 强制扫描（必须执行）
+
+**无论快速还是深度模式，必须执行以下步骤。** 防止 AI 在后续阶段编造表名和字段名。
+
+### 第一步：查找 Schema 定义文件
+
+```bash
+find . \( -name "schema.prisma" -o -name "*.model.ts" -o -name "*.entity.ts" \
+  -o -name "models.py" -o -name "models.go" \
+  -o -name "*.sql" -o -name "migration*" \
+  \) \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
+  -not -path "*/build/*" -not -path "*/vendor/*" | head -30
+```
+
+支持的格式：
+
+| 框架 | 识别文件 |
+|---|---|
+| Prisma | `prisma/schema.prisma` |
+| SQLAlchemy / Django | `**/models.py` |
+| TypeORM | `**/*.entity.ts` |
+| Mongoose | `**/*.model.ts`（检查 mongoose schema） |
+| Java JPA / Hibernate | `**/entity/*.java`、`**/model/*.java`（含 `@Entity` / `@Table` 注解的类） |
+| MyBatis | `**/*Mapper.xml`（提取 `resultMap` 和表名） |
+| Go GORM | `**/models.go`、`**/model.go` |
+| Drizzle | `**/schema.ts` |
+| 原始 SQL | `**/migrations/*.sql` |
+
+### 第二步：生成 Schema 摘要
+
+**只记录表名 + 说明 + 字段数量，不展开字段细节。** 写入 ARCHITECTURE.md：
+
+```markdown
+## 数据模型（摘要）
+
+| 表名 | 说明 | 字段数 | 来源文件 |
+|---|---|---|---|
+| users | 用户表 | 12 | `src/entity/User.java` |
+| roles | 角色表 | 5 | `src/entity/Role.java` |
+| orders | 订单表 | 18 | `prisma/schema.prisma` |
+
+### 关系
+- users 1:N roles
+- users 1:N orders
+```
+
+如果项目没有数据库 → 写"本项目无数据库"，后续阶段不准引用任何表。
+
+### 第三步：在后续命令中按需深挖
+
+**brainstorm/propose/plan 阶段，根据当前需求只读取相关表的详细 schema。**
+
+执行规则：
+1. 先读 ARCHITECTURE.md 的 Schema 摘要，确定涉及哪些表
+2. 只读取相关表的源文件（`cat src/entity/User.java`）
+3. 没涉及的表不要读，节省上下文
+4. 如果摘要中没有但需要新表 → 必须在 propose 的 design.md 中声明
+
+**铁律：所有阶段引用的表名必须来自 Schema 摘要列表，或 design.md 中声明的新增表。**
+
+## 🚨 框架隐形规则扫描（必须执行）
+
+**无论快速还是深度模式，必须执行。** 防止 AI 生成 SQL/代码时违反项目框架的自动处理机制。
+
+### 为什么需要这一步
+
+很多项目有"隐形规则"——某些字段由框架自动处理，SQL 里不需要写；某些拦截器会自动注入条件，手动写反而会冲突。这些规则不在 schema 里，AI 扫不到就会犯错。
+
+**典型踩坑：**
+- MyBatis 多租户插件自动注入 tenant_id → SQL 里再写就重复了
+- JPA @CreatedDate 自动填充 create_time → INSERT 里再写就冲突了
+- 逻辑删除拦截器把 DELETE 改成 UPDATE → AI 直接写 DELETE FROM 就错了
+
+### 扫描步骤
+
+```bash
+# 1. MyBatis 拦截器 / 插件配置
+find . \( -name "*Interceptor*.java" -o -name "*Plugin*.java" \
+  -o -name "mybatis-config.xml" -o -name "mybatis*.yml" -o -name "mybatis*.yaml" \) \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
+
+# 2. JPA / Hibernate 配置和审计注解
+find . \( -name "*Auditor*.java" -o -name "*EventListener*.java" \
+  -o -name "persistence.xml" -o -name "application*.yml" -o -name "application*.yaml" \) \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
+
+# 3. Django 配置（中间件、模型 Meta）
+find . -name "settings.py" -not -path "*/node_modules/*" | head -5
+find . -name "models.py" -not -path "*/node_modules/*" | head -10
+
+# 4. SQLAlchemy 事件监听
+find . \( -name "*event*.py" -o -name "*listener*.py" -o -name "*mixin*.py" \) \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -10
+
+# 5. Prisma 中间件 / 扩展
+cat prisma/schema.prisma 2>/dev/null | grep -i "middleware\|plugin\|previewFeatures"
+
+# 6. Go GORM 插件 / 回调
+find . -name "*.go" -not -path "*/vendor/*" | xargs grep -l "gorm:\|Callback\|Plugin" 2>/dev/null | head -10
+
+# 7. TypeORM 订阅器 / 监听器
+find . -name "*.ts" -not -path "*/node_modules/*" | xargs grep -l "EventSubscriber\|@BeforeInsert\|@AfterUpdate\|@DeleteDateColumn" 2>/dev/null | head -10
+
+# 8. Rails / Active Record 回调
+find . -name "*.rb" -not -path "*/vendor/*" | xargs grep -l "before_save\|before_create\|acts_as_paranoid\|acts_as_tenant" 2>/dev/null | head -10
+
+# 9. Laravel / Eloquent 作用域和 trait
+find . \( -name "*Scope*.php" -o -name "boot*.php" -o -name "ServiceProvider.php" \) \
+  -not -path "*/vendor/*" | head -10
+
+# 10. 通用逻辑删除 / 审计字段检测
+find . \( -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.ts" \
+  -o -name "*.php" -o -name "*.rb" \) \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" \
+  -not -path "*/dist/*" -not -path "*/build/*" \
+  | xargs grep -li "is_deleted\|deleted_at\|soft_delete\|paranoid\|tenant_id\|tenantId" 2>/dev/null | head -20
+```
+
+### 将结果写入 CONVENTIONS.md
+
+**创建或追加到 `.sillyspec/codebase/CONVENTIONS.md`，添加"框架隐形规则"章节。**
+
+格式：
+
+```markdown
+## 框架隐形规则
+
+### 自动注入字段（SQL 中不要手动写）
+
+| 字段 | 来源 | 说明 |
+|---|---|---|
+| tenant_id | MyBatis 多租户拦截器 TenantLineInnerInterceptor | 自动注入租户过滤条件，SQL 不需要 WHERE tenant_id=? |
+| is_deleted | 逻辑删除拦截器 | DELETE 自动改为 UPDATE xxx SET is_deleted=1 |
+
+### 自动填充字段（INSERT/UPDATE 不需要手动赋值）
+
+| 字段 | 来源 | 说明 |
+|---|---|---|
+| create_time | JPA @CreatedDate / MyBatis-Plus MetaObjectHandler | INSERT 时自动填充 |
+| update_time | JPA @LastModifiedDate / MyBatis-Plus MetaObjectHandler | INSERT 和 UPDATE 时自动填充 |
+| create_by | MetaObjectHandler | 从 SecurityContext 获取当前用户 |
+
+### 查询增强（框架自动追加条件）
+
+| 规则 | 说明 |
+|---|---|
+| 数据权限过滤 | 某些表自动追加 WHERE 条件，SQL 中不需要手动加 |
+| 软删除过滤 | 查询自动排除 is_deleted=1 的数据，SQL 不需要 WHERE is_deleted=0 |
+
+### DELETE 行为
+
+- 不要写 `DELETE FROM` → 使用 `UPDATE xxx SET is_deleted = 1 WHERE id = ?`
+```
+
+**如果项目没有发现任何隐形规则** → 写"未发现框架级别的自动处理配置，SQL 可以按常规方式编写"。
+
+**铁律：后续阶段生成 SQL 或数据操作代码时，必须遵守这些规则。违反 = 生成的代码会报错或产生数据错误。**
+
+## 🚨 实体继承规范扫描（必须执行）
+
+**无论快速还是深度模式，必须执行。** 防止 AI 新建表时漏掉基类的通用字段，导致 MyBatis-Plus/JPA 自动查询报 Unknown column。
+
+### 为什么需要这一步
+
+很多项目用实体基类（BaseModel、BaseEntity、BasePO 等）定义通用字段（审计字段、逻辑删除、多租户等）。子类继承基类后，ORM 框架会自动查询这些字段。如果新建表的 DDL 漏掉了这些列，SQL 就会报错。
+
+**典型踩坑：**
+- 实体类继承了 BaseModel，有 remarks、dept_id 字段
+- AI 生成建表 SQL 时只写了业务字段，漏了通用字段
+- MyBatis-Plus 自动 SELECT 包含 remarks → Unknown column
+
+### 扫描步骤
+
+```bash
+# 1. Java: 查找实体基类（BaseModel / BaseEntity / BasePO）
+find . \( -name "Base*.java" -o -name "Abstract*.java" \) \
+  -path "*/entity/*" -o -path "*/model/*" -o -path "*/po/*" -o -path "*/entity/*" \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
+
+# 2. Java: 查找 @MappedSuperclass 注解的类
+find . -name "*.java" -not -path "*/node_modules/*" -not -path "*/.git/*" \
+  | xargs grep -l "@MappedSuperclass" 2>/dev/null | head -10
+
+# 3. Java: 查看子类继承关系
+grep -rn "extends Base" --include="*.java" \
+  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
+
+# 4. Python / Django: 查找 Abstract 模型
+find . -name "models.py" -not -path "*/node_modules/*" | xargs grep -l "class.*Abstract\|class.*Base" 2>/dev/null | head -10
+
+# 5. Go: 查找嵌入的 BaseModel struct
+find . -name "*.go" -not -path "*/vendor/*" | xargs grep -l "type.*struct" | xargs grep -l "BaseModel\|BaseEntity" 2>/dev/null | head -10
+
+# 6. TypeORM: 查找 @Entity 基类的子类
+find . -name "*.entity.ts" -not -path "*/node_modules/*" | xargs grep -l "extends\|@ChildEntity" 2>/dev/null | head -10
+
+# 7. Prisma: 查找 model 共用字段（通过 generator 或注释）
+cat prisma/schema.prisma 2>/dev/null
+
+# 8. Rails: 查找 ApplicationRecord concern
+find . -name "*.rb" -not -path "*/vendor/*" | xargs grep -l "include.*Concern\|include.*Module" 2>/dev/null | head -10
+
+# 9. Laravel: 查找 Model trait
+find . -name "*.php" -path "*/Models/*" -not -path "*/vendor/*" | head -10
+```
+
+### 将结果写入 CONVENTIONS.md
+
+在"框架隐形规则"章节后追加：
+
+```markdown
+## 实体继承规范
+
+### 基类通用字段（新建表必须包含）
+
+以下字段来自基类 BaseModel，所有子类实体自动继承，DDL 必须包含：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | BIGINT | 主键 |
+| remarks | VARCHAR(500) | 备注 |
+| dept_id | BIGINT | 部门ID |
+| create_time | DATETIME | 创建时间 |
+| update_time | DATETIME | 更新时间 |
+| create_by | VARCHAR(64) | 创建人 |
+| update_by | VARCHAR(64) | 更新人 |
+| is_deleted | TINYINT(1) | 逻辑删除 |
+
+### 铁律
+- 新建表的 DDL 必须包含基类的所有字段，不能只写业务字段
+- ORM 自动查询基类字段，数据库缺少这些列会报 Unknown column
+- 如果基类有变更（新增通用字段），需要同步更新所有子表的 DDL
+```
+
+**注意：** 上表是示例，实际字段必须从扫描到的基类源码中提取，不要编造。
+
+**如果项目没有实体基类** → 写"本项目没有实体基类，所有字段在各自实体中定义"。
+
+**铁律：后续阶段新建表或修改表结构时，必须包含基类的所有通用字段。**
+
+---
+
+**快速扫描生成 3 份文档：**
+
+创建目录 `mkdir -p .sillyspec/codebase`
+
+**1. `.sillyspec/codebase/STACK.md`** — 技术栈
+**2. `.sillyspec/codebase/STRUCTURE.md`** — 目录结构
+**3. `.sillyspec/codebase/PROJECT.md`** — 项目概览
+
+---
+
+## 深度扫描
+
+### Step 0: 运行预处理脚本（必须）
+
+**深度扫描前，必须先运行预处理脚本。** 这是零 token 的 shell 操作：
+
+```bash
+bash scripts/scan-preprocess.sh [扫描区域]
+```
+
+如果 `scripts/scan-preprocess.sh` 不存在（Windows 或远程项目），跳过此步骤，AI 直接基于快速扫描结果进行深度分析。
+
+**预处理脚本会自动完成：**
+- 统计源文件数量和大小
+- 估算扫描耗时（按文件数量动态计算，不是写死的 3 分钟）
+- 提取配置文件内容（package.json、pom.xml 等）
+- 提取目录结构树
+- 提取 import/依赖关系（按语言分别分析）
+- 提取类名/函数名/注解（Java @Entity、@Controller 等）
+- 检测数据库 Schema 文件位置
+- 检测框架和 ORM
+- 检测框架配置文件（拦截器、审计、基类等）
+
+所有结果写入 `.sillyspec/codebase/SCAN-RAW.md`。
+
+**脚本输出示例：**
+```
+📊 文件统计：
+  Java: 280
+  Vue: 180
+  配置文件: 3
+  ────────────────
+  源文件总计: 460 个
+  源码总大小: 3200KB
+  预计耗时: 约 5-8 分钟
+  上下文风险: 中
+```
+
+### Step 1: 断点续扫检查
+
+**检查已生成的文档，跳过已完成的：**
+
+```bash
+for f in STACK ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS; do
+  if [ -f ".sillyspec/codebase/${f}.md" ]; then
+    echo "✅ ${f}.md 已存在，跳过"
+  else
+    echo "⬜ ${f}.md 待生成"
+  fi
+done
+```
+
+**只生成缺失的文档。** 如果中断后重新执行，不会重复生成已有文档，也不会重复消耗 token。
+
+将检查结果展示给用户：
+```
+📊 扫描进度检查：
+  ✅ STACK.md         已存在
+  ✅ ARCHITECTURE.md  已存在
+  ✅ STRUCTURE.md     已存在
+  ⬜ CONVENTIONS.md   待生成 ← 从这里继续
+  ⬜ INTEGRATIONS.md  待生成
+  ⬜ TESTING.md       待生成
+  ⬜ CONCERNS.md      待生成
+
+  继续生成剩余 4 份文档。
+```
+
+### Step 2: 基于 SCAN-RAW.md 分析
+
+**不要直接读取原始源码。** 读取预处理脚本生成的 SCAN-RAW.md：
+
+```bash
+cat .sillyspec/codebase/SCAN-RAW.md
+```
+
+基于 SCAN-RAW.md 中的结构化信息，**只按需深挖**相关文件：
+
+1. **架构分析** → 如果 SCAN-RAW.md 标注了 460 个文件，不要全部读。读核心入口文件 + 目录结构推断架构
+2. **编码约定** → 如果 SCAN-RAW.md 有 import 分析，基于高频 import 推断约定。必要时抽样读 3-5 个文件确认
+3. **集成分析** → 读 SCAN-RAW.md 中的配置文件内容，不需要重新读原始文件
+4. **数据库 Schema** → 读 SCAN-RAW.md 中标注的 schema 文件位置，只读相关文件
+
+**铁律：每份文档写完立即保存。** 不要攒在一起最后统一写。这样即使中断，已生成的文档不会丢失。
+
+**按以下顺序生成缺失的文档：**
+
+1. `.sillyspec/codebase/STACK.md` — 技术栈（基于 SCAN-RAW.md 的框架检测 + 配置文件）
+2. `.sillyspec/codebase/ARCHITECTURE.md` — 架构（含数据模型摘要）
+3. `.sillyspec/codebase/STRUCTURE.md` — 目录结构（基于 SCAN-RAW.md 的目录分布）
+4. `.sillyspec/codebase/CONVENTIONS.md` — 代码约定
+5. `.sillyspec/codebase/INTEGRATIONS.md` — 集成
+6. `.sillyspec/codebase/TESTING.md` — 测试现状
+7. `.sillyspec/codebase/CONVENTIONS.md` — 编码约定（含框架隐形规则）
+8. `.sillyspec/codebase/CONCERNS.md` — 技术债务和风险
+
+同时更新 `.sillyspec/PROJECT.md`。
+
+---
+
+## 扫描完成
+
+### 快速扫描完成后
+
+**用 CLI 验证结果：**
+
+```bash
+sillyspec status --json
+```
+
+展示给用户：
+> ✅ 快速扫描完成！
+> 
+> 生成文档到 `.sillyspec/codebase/`：
+> - STACK.md — 技术栈
+> - STRUCTURE.md — 目录结构
+> - PROJECT.md — 项目概览
+
+**下一步由 CLI 决定：**
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。
+
+### 深度扫描完成后
+
+**用 CLI 验证结果：**
+
+```bash
+sillyspec status --json
+```
+
+CLI 应返回 `phase: "brainstorm"`。如果返回其他阶段，说明有文档缺失，需要补全。
+
+展示给用户：
+> ✅ 深度扫描完成！
+> 
+> 生成 7 份文档到 `.sillyspec/codebase/`：
+> - STACK.md — 技术栈
+> - ARCHITECTURE.md — 架构（含数据模型摘要）
+> - STRUCTURE.md — 目录结构
+> - CONVENTIONS.md — 代码约定
+> - INTEGRATIONS.md — 集成
+> - TESTING.md — 测试现状
+> - CONCERNS.md — 技术债务和风险
+
+**下一步由 CLI 决定，不要自己编建议：**
+
+```bash
+sillyspec next
+```
+
+将 CLI 返回的命令推荐给用户。
+
+### 工作区扫描完成后
+
+> ✅ 工作区扫描完成！
+>
+> - 子项目 frontend：`frontend/.sillyspec/codebase/`（快扫，3 份文档）
+> - 子项目 backend：`backend/.sillyspec/codebase/`（深扫，7 份文档）
+> - 工作区概览：`.sillyspec/workspace/CODEBASE-OVERVIEW.md`
+>
+> 建议下一步：`/sillyspec:brainstorm '你的需求'`
+
+---
+
+## Step 6: Git 提交
+
+```bash
+git add .sillyspec/
+git commit -m "chore: sillyspec scan - codebase mapped"
+```
+
+## 绝对规则
+
+- 不修改任何代码
+- 文档必须包含真实文件路径（用反引号格式）
+- 有具体代码模式就列出来（不要写模糊的描述）
+- 如果项目为空 → 告知用户使用 `/sillyspec:init` 初始化新项目
+- **交互模式下，每一步都要等用户回复再继续，不要一次性全部输出**
+
+### 路径校验（写入后立即检查）
+
+**每份文档写完后，必须用脚本验证路径正确。这是防止 AI 把文件写错目录的硬约束。**
+
+```bash
+# 检查所有 codebase 文档是否在正确位置
+for f in STACK ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT SCAN-RAW; do
+  if [ -f ".sillyspec/codebase/${f}.md" ]; then
+    echo "✅ .sillyspec/codebase/${f}.md"
+  elif [ -f "${f}.md" ] || [ -f ".sillyspec/${f}.md" ] || [ -f "codebase/${f}.md" ]; then
+    echo "❌ ${f}.md 路径错误！必须在 .sillyspec/codebase/ 下"
+    # 自动修正：移动到正确位置
+    mkdir -p .sillyspec/codebase
+    if [ -f "${f}.md" ]; then mv "${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: ${f}.md → .sillyspec/codebase/${f}.md"; fi
+    if [ -f ".sillyspec/${f}.md" ]; then mv ".sillyspec/${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: .sillyspec/${f}.md → .sillyspec/codebase/${f}.md"; fi
+    if [ -f "codebase/${f}.md" ]; then mv "codebase/${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: codebase/${f}.md → .sillyspec/codebase/${f}.md"; fi
+  fi
+done
+
+# 额外检查：扫描整个项目，找出误放的文档
+for f in $(find . -maxdepth 2 -name "ARCHITECTURE.md" -o -name "STACK.md" -o -name "STRUCTURE.md" -o -name "CONVENTIONS.md" -o -name "INTEGRATIONS.md" -o -name "TESTING.md" -o -name "CONCERNS.md" -o -name "PROJECT.md" | grep -v ".sillyspec/codebase/"); do
+  if [ -f "$f" ]; then
+    echo "❌ 发现误放文件: $f（应该在 .sillyspec/codebase/ 下）"
+    mkdir -p .sillyspec/codebase
+    name=$(basename "$f")
+    mv "$f" ".sillyspec/codebase/${name}"
+    echo "  已自动修正: $f → .sillyspec/codebase/${name}"
+  fi
+done
+```
+
+**铁律：所有扫描生成的文档必须且只能在 `.sillyspec/codebase/` 目录下。** 如果发现 AI 生成到了其他位置，立即移动到正确位置。
+
+### 自检门控（Hard Gate）
+
+- [ ] STACK.md 是否包含主要语言和框架？
+- [ ] ARCHITECTURE.md 是否描述了整体架构？
+- [ ] STRUCTURE.md 是否包含目录结构？
+- [ ] CONVENTIONS.md 是否描述了编码约定？（深度扫描）
+- [ ] INTEGRATIONS.md 是否列出外部依赖？（深度扫描）
+- [ ] TESTING.md 是否描述了测试状况？（深度扫描）
+- [ ] CONCERNS.md 是否列出了技术债务？（深度扫描）
+- [ ] PROJECT.md 是否生成？
+
+### 脚本校验（硬验证）
+
+Hard Gate 自检通过后，运行校验脚本：
+
+```bash
+bash scripts/validate-scan.sh .sillyspec/codebase
+```
+
+- 脚本返回 0 → 自检通过，继续
+- 脚本返回非 0 → 根据错误提示修正文档，重新运行脚本